diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex')
88 files changed, 18395 insertions, 6273 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/ChangeLog b/Master/texmf-dist/doc/latex/pgfplots/ChangeLog index c1fe62d1ee6..8e58a522a74 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/ChangeLog +++ b/Master/texmf-dist/doc/latex/pgfplots/ChangeLog @@ -1,3 +1,876 @@ +2010-01-02 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Released version 1.3 + +2009-12-30 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - ticklabel cs did not respect the shift of 'tick align=outside'. Fixed + that. + +2009-12-29 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed a bug with line plots and plot expression. + - fixed a rarely occuring bug in auto-tick positioning: the case "if just + one tick position available" assumed log axes. + - changed 'try min ticks' for 3D plots from 4 to 3 + - implemented support for a "too few tick labels" check for linear axes + - changed activation of 'every 3d description' such that it is processed + earlier. It should now be possible to overwrite more keys for 3D plots. + - updated docs for clickable lib. + +2009-12-23 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - the color bar modification of yesterday was not completely correct, + fixed that + - width/height are now processed with \pgfmathparse + - fixed bug in 'colorbar horizontal' style + +2009-12-22 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved extensibility of the point meta input methods + - fixed buggy treatment of some automatic cross references in manual + - fixed bug: log basis x changed the formatting of logarithmic y and z + axes as well. + - color bars can now be positioned using the axis description cs of the + PARENT axis. + +2009-12-18 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed buggy treatment of extra ticks in 3D axes + +2009-12-12 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed a reverse axis special case which lead to improper placing of tick + labels (they incorporated the tick width with wrong sign) + +2009-12-11 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added and documented |[xy]bar legend| styles and |[xy]bar interval + legend| styles + - renamed 'every mesh legend' to 'mesh legend' for consistency + - improved 'mesh legend' (rescaled and reshiftet it a bit) + +2009-12-10 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed expansion bug in 'scatter/classes' + - added the \addlegendimage extension which simply provides options for a + further legend image. + +2009-12-09 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added variant |xticklabels from table| + +2009-12-08 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added \pgfplotstabletranspose command. + +2009-12-07 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - the 'log basis *' implementation didn't handle unbounded coords + correctly; fixed that + +2009-12-05 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed bug in processing of axis lines. + The new version should also allow 3D axis line variations and reversed axes + - fixed bug occuring for reversed axes and the 'above origin' (and + friends) anchors. + + +2009-12-04 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed plot graphics and reversed axes + - allowed reversed color bars + - fixed axis line variations and reversed axes + +2009-12-03 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added '3d box=complete' feature + +2009-12-02 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - found and fixed bug: tick labels could penetrate the axis. This should + no longer happen. + +2009-11-26 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added \pgfplotsinvokeforeach + - worked on docs + +2009-11-24 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed a (rarely occuring) bug in plot table where the detection if the + arg is a file- or structure failed. + +2009-11-23 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added the 'color list' cycle list which contains only colors (now + markers). This might be handy in conjunction with |cycle multi list|. + - updated docs. + - a copy of the automatic image externalization 'external' lib is now + available when using + \usepgfplotslibrary{external} + even without Tikz CVS installed. + - 'width' and 'height' can now be queried with + \pgfkeysvalueof{/pgfplots/width} while axis descriptions are processed. + - extended the |function graph cut y| by a |foreach| feature to provide + the input tables. + +2009-11-19 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed bug with cycle multi list: it couldn't be overridden with cycle + list or cycle list name. + - added \addlegendentryexpanded + +2009-11-18 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - wrote primitive exception handling for better error messages (in + pgfplotscore.code.tex) + - fixed \thisrow in create on use statements: it did not respect aliases. + +2009-11-18 Nick Papior Andersen <zerothi@users.sourceforge.net> + + - Added a key |line legend| which sets the |legend image code| back + to its original value. This makes it easy to use area legends + together with line legends + - The docs have been updated accordingly. See the example under + |area legend| + +2009-11-15 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - auto xrefs now support point coordinate systems. + - auto xrefs now provide an interface to deal with tricky active + characters (for |-) + +2009-11-13 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved sanity checking for plot file by introducing trailing 0 0 0 to each line + +2009-11-11 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved docs for 3D coordinate ordering. + - fixed bug with |samples y|. + +2009-11-10 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved plot gnuplot and 3D interface + - fixed some 3D plot expressions things (samples y, y domain where not + completely correct) + +2009-11-06 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - tuned the |footnotesize| style. + +2009-11-03 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added |rawx|, |rawy| and |rawz| math constants to access unprocessed + input coordinates. + +2009-10-30 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved loop macros + +2009-10-27 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved the interface for |nodes near coords| + - added starred key versions for |use mapped color*|, |nodes near + coords*|, |scatter/classes*|. These starred versions APPEND code to |@pre + marker code| insteaf of overwriting it. + - documented |nodes near coords| and the starred variants for scatter + plots. + +2009-10-26 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added col sep=tab + +2009-10-23 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Fixed buggy xshift and yshift keys: they shifted axis descriptions too + much + - fixed buggy 'hide x axis': it lead to removal of *y*tick marks and grid + lines. + - during plot table: renamed \x, \y, \z etc to \columnx, \columny. They + posed naming conflicts (and are perhaps useless anyway). + +2009-10-20 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - It is now possible to access all table columns as long as |\addplot + table| is working. Possible occurences are coordinate filters or point + meta expressions. + - |point meta={<expression>}| won't yield error messages any longer if the + expression contains temporary control sequences like \thisrow. + - rel axis cs now invokes the math parser. + - added 'restrict expr to domain' + +2009-10-14 Nick Papior Andersen <zerothi@users.sourceforge.net> + + - Added a MakeFile for the test folder. One can use + this for compiling sections individually. I.e.: + * make pgfplotstest.libs.groupplots.tex + would yield only typesetting of the groupplots + test section. + - Currently it cannot handle more than one section at a time + although it can process the whole by calling: + * make all + * make test + * make pgfplotstest.pdf + which are all equivalent! + +2009-10-13 Nick Papior Andersen <zerothi@users.sourceforge.net> + + - Changed documentation for units and groupplots library + - Updated code of groupplots with filtering keys + +2009-10-13 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Improved placing of axis labels: the |near ticklabel| anchor was not + completely correct. + +2009-10-12 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added |cycle multi list|. + +2009-10-08 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added |axis background| + +2009-10-08 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed buggy scanline detection for plot table. + - fixed support for special anchors when non-rectangular shapes are used. + - added support for legend in scatter/classes. + +2009-10-06 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - revised manual and worked on cross referencing + - fixed buggy tick show tests for non-boxed axis lines + +2009-10-05 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - |plot coordinates| now supports mathematical expressions. + +2009-10-03 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Manual: added (auto-generated) document-internal pdf links and + implemented syntax analyser for codeexamples to + generate cross-references automatically. + +2009-09-29 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed reversed axes for 3D axes + - added new, experimental feature 'allow reversal of rel axis cs'. It + affects 'rel axis cs' and 'ticklabel cs' in case of reversed axes. + +2009-09-26 Nick Papior Andersen <zerothi@users.sourceforge.net> + + - added a new library which can group plots. + * \usepgfplotslibrary{groupplots} + - a new environment \begin{groupplot} has been created + - within the environment a command \nextgroupplot[<option>] + can be used. + - groupplots can easily typeset several plots in a matrix + style so that they are aligned + - it is possible to limit the tick labels to one side of + the matrix, be it x tick labels at only the top row or + the bottom row. Or the y tick labels only at the first or + last column, on the left or the right, respectively + - a quick documentation for the new library has been + introduced + - \usepgfplotslibrary has been modified such that it + detects loaded files from \usetikzlibrary + +2009-09-25 Nick Papior Andersen <zerothi@users.sourceforge.net> + + - restructured the reference manual file. All files: + * pgfplots.reference.<name>.tex + was in the old pgfplots.reference.tex file + +2009-09-25 Nick Papior Andersen <zerothi@users.sourceforge.net> + + - changed the surfshading library name to be consistent with the + new names. In conjunction the drivers of the surfshading library + has been changed accordingly. + - the unit library has a more customizable usage of typesetting units + - the unit library automatically sets units on when loaded + - updated the documentation according to changes done in unit library + - the command \usepgfplotslibrary now loads both: + * "tikzlibrarypgfplot.<lib>.code.tex" + * "pgflibrarypgfplot.<lib>.code.tex" + - added the environment \begin{pgfplotslibrary}...\end{pgfplotslibrary} + to the manual which shows how the user can import a library. + Displaying the following: + * \usepgfplotslibrary{<lib>} + * \usetikzlibrary{pgfplots.<lib>} + - updated the doc to use the above command where needed + +2009-09-24 Nick Papior Andersen <zerothi@users.sourceforge.net> + + - added backwards compatibility for the libraries, i.e. recreated + old files with only contents '\use...library{<package>}' + - added the command \usepgfplotslibrary which should be used + if users wants a clearer vision of where libraries are loaded from + - moved the unit test into proper location + +2009-09-24 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed bug: the \pgfplotspointaxisorigin was not clipped properly, + resulting in number too large bugs. + +2009-09-23 Nick Papior Andersen <zerothi@users.sourceforge.net> + + - changed the names of some of the files in the package. Namely: + * doc/latex/pgfplots/pgfplots.reference.units.tex -> doc/latex/pgfplots/pgfplots.libs.units.tex + * tex/generic/pgfplots/libs/tikzlibrarydateplot.code.tex -> tex/generic/pgfplots/libs/tikzlibrarypgfplots.dateplot.code.tex + * tex/generic/pgfplots/pgfplots.units.tex -> tex/generic/pgfplots/libs/tikzlibrarypgfplots.units.code.tex + * tex/generic/pgfplots/pgfplots.stackedplots.code.tex -> tex/generic/pgfplots/pgfplotsstackedplots.code.tex + * tex/latex/pgfplots/libs/tikzlibrarypgfplotsclickable.code.tex -> tex/latex/pgfplots/libs/tikzlibrarypgfplots.clickable.code.tex + This is done to be more consistent in naming convention. As old "pgfplotsclickable" and "dateplot" + libraries has changed names former versions are not compatible. This should in some way be fixed. + - updated the doc according to the new name convention + - updated the "pgfplots.core.code.tex" to use the new names + - changed the unit to a library and moved it to "libs" in manual + - added a "mkdir" command in the MakeFile such that the user who has + just downloaded the package doesn't need to make the "gnuplot" directory by hand + + +2009-09-22 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed table loading: the NL character was present as a space after each + read line, which made col sep!=space buggy + - fixed manual bugs + +2009-09-20 Nick Papior Andersen <zerothi@users.sourceforge.net> + + - added the label units. It is now possible to add units in the labels such + such that it can easily be maintained and edited. + - a documentation of the implementation is added. + +2009-09-10 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added the 'plot box ratio' feature. + +2009-09-09 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added the 'nodes near coords' feature (especially useful for bar + plots). It draws nodes besides/above the coordinates and shows the + coordinate value. + - Added the 'variable y' feature. + - Implemented support for non uniform color map specifications. + +2009-09-07 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added |each nth point| filter + - Added |restrict [xyz] to domain| filter + - Improved docs + +2009-09-04 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed 'unbounded coords=jump' for the log case + +2009-09-03 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added first version of 'unbounded coords=jump' method. + Appears to work for line plots as it ought to. + - added support for mesh plots as well + +2009-09-02 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Implemented 'z buffer=auto' and 'z buffer=reverse x seq' and 'z + buffer=reverse y seq' modes. The default z buffer for surface plots is now + 'auto' + - changed drawing sequence of minor and major tick/grid lines. + - Fixed bug related to 'forget plot' (legends didn't work as they should) + - Fixed bug: /tikz/ybar and /pgfplots/ybar did not work as documented + +2009-09-01 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Fixed y tick scale label for the new label placement stuff. + - Introduced sanity checking for point meta data. + + +2009-08-31 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added sanity check to avoid usage of \thisrow in point meta arguments. + +2009-08-12 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - the '[xyz]tick=data' feature now suppresses multiple occurances of the + same tick (a very simple method, it checks for *exact* matches only). + - removed the cause of a missing character warning + +2009-08-11 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Fixed processing of 'z buffer=sort' for log axes. + - Fixed buggy \ticknum handling: the '[xyz]ticklabels' lists did not work + properly. + +2009-07-30 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added check for 'every 3d view {<h>}{<v>}' styles which may prepare + specific options. + +2009-07-29 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed |log basis [xyz]| processing in clickable lib. + - clickable lib: there was a bug in the drag'n'drop gradient computation + of semi log plots - gradients were computed base e although they should + be base 10. + - implemented 'mesh/ordering=colwise' for 'shader=interp'. + + +2009-07-27 Stefan Tibus <sjti@gmx.net> + + - Added the 'plot shell' and 'plot table shell' feature to plot output of + arbirtrary system calls. + +2009-07-27 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added auto translation pgf => gnuplot for 'plot gnuplot'. It works for + '^' => '**'. + +2009-07-24 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added the 'tick scale binop' feature to allow simple change from '\cdot' to '\times' + - added the 'log basis [xyz]' key. + +2009-07-23 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed positioning of tick scale labels for 3D case. + +2009-07-21 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - replaced '\definecolor' by '\pgfutil@definecolor' for ConTeXt + compatibility. + - renamed 'ticklabel dist' to 'ticklabel shift' to provide a more + consistent naming convention. + +2009-07-08 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added sanity checking for non-existing colormaps + +2009-07-07 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed bug with 'mesh/ordering=colwise' + +2009-07-04 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added 'sloped like [xyz] axis' key for label alignment, + - added '[xyz]ticklabel cs' coordinate system, + - added 'near [xyz]ticklabel' anchor for every node + +2009-07-02 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed a bug related to the 'sqrt(num points)' thing for mesh plots (the + check for rounding errors did not work as expected). + - fixed bug in auto-scan line computation for plot table: it counted also + the header line with column names. + +2009-06-29 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed a bug in the 'meta min/meta max' handling: the arguments have not + been parsed correctly (the bug is not that old) + +2009-06-25 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added style 'every 3d description' and changed option processing such + that description style changes are applied as soon as the axis' dimension + is known (2d or 3d). + +2009-06-24 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed treatment of 'scan line length' for some plot table special + issues. + +2009-06-22 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - using '/tikz/variable=\t' now also defines the shorthand function 't' + ATTENTION: this requires the most recent PGF CVS version! + - added temporary family for /tikz/variable to fix its usage in pgfplots' + axes + +2009-06-17 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added draft for 'sloped' feature for axis labels + - improved the special anchor label alignment: it does not respect the + current transformation matrix (I renamed it to 'near ticklabel') + +2009-06-16 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved sanity checking for short-hand styles for legend placement + - improved sanity checking for surfshading lib + - started to write code for label placement + backwards compatibility + switches. It is not complete yet. + +2009-06-15 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved interface for mesh/surface plots. + +2009-06-11 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added |no marks| key and updated docs. + - added short-hand styles for legend placement. + +2009-06-10 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed shift transformations provided to an axis - these did not work + previously [requires recent pgf version]. + - improved colorbar implementation + - added 'ticklabel style' alias to 'tick label style' + - improved support for pgf 2.00 backwards compatibility + +2009-06-09 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - besides a lot of manual improvements, I have also fixed the |point meta min|/max + processing such that they work properly for the general case and for + special cases. + - implemented a user interface to draw arbitrary boxes in 'plot graphics'. + - added small optimizations to key setting procedures. + + +2009-05-30 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - documented and improved the expression+table input method + +2009-05-29 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed the 'ticklabel cs' for 2D plots - it queried 3D stuff which wasn't + initialised. + +2009-05-28 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed correct implementation of |overlay| for tick labels - my recent + changes required bounding box modifications and disabled that. + - Provided a (sophisticated) fix for the problem with legend styles: + now, it is possible to set 'legend image code' in \addplot AND the legend + remembers the draw modes correctly. + - to do this, I used 'current plot style' here - which handles key paths, + draw modes and all that stuff correctly. + - added legend image for mesh/surface plots + +2009-05-27 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed a (stupid) bug in the processing of skewed/rotated axis unit + vectors (|x| or |y| keys). It is now processed correctly. + - added sanity checking for stacked plots: now, an error message is raised + if the number of points of successive stacked plots does not match. + +2009-05-26 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed the implementation of 'current axis' for unfinished axes - it did + not work since the rewrite of alignment features. + - moved the declaration of the 'current axis' leight weight node before + the processing of stored plots. This means it is possible to reference it + in path/plot commands. + - fixed the '\addplot+[ black]' bug - the white space doesn't hurt any + longer. + - \ref now works properly inside of moving arguments (as \caption) without + the need of explicit \protect ion. + +2009-05-25 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added 'reverse legend' feature, thanks to Tom Cashman for the + implementation! + +2009-05-22 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - now I remembered why `legend image code' did process its arguments in a + separate scope -- and I restored it (and documented the change). + Now: the plot style is activated before `legend image code' is evaluated. + This allows to redefine `legend image code' inside of plot styles. + - fixed bug: the re-using of outer normal vector did not work properly + +2009-05-20 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed the default 'legend image code' things - they also needed to be + changed. + - added tolerances to tick placement code: now, tick labels are placed if + they are no more than 0.05pt beyond the axis limits. The threshold can be + configured. + - improved manual section for tick docs: introduced subsections and moved + special stuff into a "fine tuning" section. + +2009-05-14 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed 'legend image code' - it did not provide the argument as + documented. + +2009-05-08 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Restructured the manual. Now, the "command reference" and "option + reference" has been merged into one large "reference". + The new stuff should be easier to navigate. + +2009-05-02 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - changed 'ticklabel pos' initial value to 'default'. + - added '[xyz] dir={normal,reverse}' keys (work correctly for 2d, + not yet for 3d) + +2009-04-27 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed several bugs which have been introduced in the latest changes + +2009-04-24 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added |preproc/expr| style to table package. + - added |fonts by sign| style to table package. + +2009-04-21 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed broken '[xyz] tick scale label style' keys + +2009-04-20 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Added the |value|, |abs value|, |upper| and |lower| options to enlarge limits. + +2009-04-17 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added public API commands \pgfplotspointouternormalvectorofaxis, + \pgfplotspointoutsideofaxis and the same for the ticklabelaxis. + +2009-04-17 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added 'rel axis' coordinate system. + +2009-04-14 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - Moved sanity checking for end-of-scanline autocompletion out of standard + plots. + +2009-04-13 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - updated error bar implementation: it works now also for 3D plots and it + is a more efficient. + ATTENTION: + *********this requires the PGF CVS version of 2009-04-13 or newer!***** + - added support for end-of-scan-line markers for 'plot coordinates' and + 'plot file': empty lines end a scan line. + This allows mesh input without explicitly providing 'rows' or 'cols'. + +2009-04-09 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added a style for string symbols as input coordinates. + +2009-04-08 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - `legend image code' now also evaluates pgfplots options. furthermore, it + can be changed inside of options for \addplot. + +2009-04-07 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added /pgfplots/colormap access=map|direct key. + - simplified input format of colormaps + - changed the anchors. Now, all anchors use the BOUNDING BOX of the axis + instead of local coordinates. This does also work for 3D and for skewed or + reversed axes. + +2009-04-06 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - table package: improved handling for empty cells in create column + statements. An empty cell will be considered as 'zero'. + - fixed axis cs for 3D case + - incorporated tick dimensions into 3D axis scaling (approximately as + before for 2D axes) + +2009-04-04 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed surface shading problem: both, pdftex and dvips now produce useful + results and the resulting pdf/ps documents can be processed by + ghostscript and standard viewers. + Switching to BitsPerCoordinate=24 fixed the problem. + + +2009-04-03 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added public interface \pgfplotsmathviewdepthxyz and + \pgfplotsmathfloatviewdepthxyz inside of an axes. + - added 'point meta=<expr>' feature: \addplot[point meta={x+y+z},scatter] ... + - removed the optimizations for the binary output sub-package - they did + not work at all. + - updated the manual examples for the new view parameters + - finished the clip-path implementation so far. It appears to work + correctly. + - implemented first semi-correct first of surfshading and dvips driver. + However, it works only after converting the ps to pdf :-( + The backwards conversion pdf->ps fails with limitcheck as before. + +2009-04-02 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - re-enabled error bars and fixed bug + - fixed newly introduced optimization of the binary output sub-package: it + lead to an infinite loop :-( + +2009-04-01 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - disabled error bars temporarily - one of my latest changes caused + problems. + - added 'cube/size [xyz]' for the cube markers + - fixed bug in cube and cube* + - Changed semantics of 'view'. It is now 'view={<azimuth>}{<elevation>}' + as in matlab. + +2009-03-31 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved 3D plot tick label alignment issue + +2009-03-30 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - found bug in error bar implementation - but I don't know where it comes + from yet. + +2009-03-27 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - implemented expression plotting features inside of 'plot table' for the + plot from structure method as well. + +2009-03-26 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added (first draft with) support for expressions in 'plot table', for example + \addplot table[x expr={\coordindex},y expr={\thisrow{std-L2} * \thisrow{maxlevel}}] {regtable}; + +2009-03-25 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added support for \coordindex inside of marker streams (interesting for + scatter plots). + +2009-03-23 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed the new placement of ticks such that is also works for 2D plots. + It will also work for reversed axes. alignment is still not functional. + +2009-03-22 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - implemented proper placement for 3D axis tick positions. + Alignment is prepared, but not functional yet. + +2009-03-21 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added some internal methods to distinguish foreground and background in + 3D axes - required for a better placement of ticks and for the axis labels + anyway. + - Added image externalization for some expensive examples to improve manual + compilation speed. + +2009-03-20 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - renamed the 'z buffer=sort coordinates' choice introduced yesterday to + 'z buffer=sort'. I'll take care that it yields useful results. + - fixed bug in the new option processing - some /tikz options were + important during \addplot, but since the new strategie silently ignores + /tikz options, I needed to add exceptions. + - added implementation for z buffer=sort and mesh plots + - allowed 3D line plots + mesh handler + - optimized new option processing + - changed default shader to faceted + +2009-03-19 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added \pgfplotsarraysort + - added |z buffer=sort coordinates| for use with scatter plots (not very useful for + any other plot type yet) + +2009-03-17 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - the point meta now always uses floating point routines internally; the + case distinctions have been eliminated. + - added keys 'point meta rel=axis wide|per plot' and 'point meta min' and + 'point meta max'. + - added 'create col/' search path to table package. + +2009-03-16 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added "cube" and "cube*" markers for 3D axes. + - added 'unique' row predicate which suppresses multiple occurances of the + same key in one designated column. + +2009-03-13 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - introduced to use rows=cols=sqrt(N) if neither rows nor cols is provided + in a mesh plot. + +2009-03-10 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - improved 'view' processing for 3D axes. + +2009-03-06 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed decoding bug of interp shader: now, acroread is able to read it! + +2009-03-05 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - provided several 3D examples in the manual and fixed corresponding bugs + in parameterized 3D plots. + +2009-03-04 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - found and fixed encoding bugs in binary conversion. The surface lib now + produces visually correct results - although acroread is still complaining + and doesn't show anything :-( + +2009-03-03 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - wrote further basic level table access commands. + - surf shading now understands the colormap. Fixed bugs in mapping of + dimen registers + - startet primitive heuristics for z buffering of mesh/surf plots in the + |mesh/z buffer| key. + - added fast prepend list + +2009-02-27 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - first semi functional version with bilinear interpolation shading (gouraud) + +2009-02-26 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - added public methods for access to table elements [untested and undocumented + so far]. + - added pgfplotslistset [untested] + - worked on binary encoding for signed integers + +2009-02-24 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - fixed enlarge z limits functionality (was broken) + - provided 3D examples in reference manual. + - improved alignment of 3D tick labels slightly + - changed semantics of enlarge limits=auto for 3D plots + +2009-02-23 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - The draw,fill bug introduced in the latest changes of 2009-02-20 appears + to be fixed now. Nevertheless, I'll need to revise those changes. + - the \label bug which also occured in this change is now fixed as well + - fixed manual typo + + - implemented functionality 'mesh/ordering' and 'mesh/flat mode={corner,mean}|. + - plot[mesh] works now also for 1D case. + +2009-02-22 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - The processing of draw options and behavior options still causes a lot + of overhead- and even bugs. At least the manual compiles now. + Maybe that wasn't my best idea... + +2009-02-20 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - changed complete processing of 'draw options' and 'behavior options'. + They are now the same, no special treatment is necessary. + +2009-02-19 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - implemented first functional mesh - and surface plots (the latter with + flag shading). + The user interface is lacking, however. And, of course, there will never + be a real renderer - but it looks really good (up to the bugs)! + +2009-02-17 Christian Feuersaenger <ludewich@users.sourceforge.net> + + - provided some more code documentation + - improved axis vector initialization for 3D plots + - provided low-level interface commands and a corresponding section in the + manual. + - implemented tick label positioning for 3D axes. It works up to orthogonal special + cases. + 2009-02-16 Christian Feuersaenger <ludewich@users.sourceforge.net> - Released version 1.2.2 (bugfix release for CTAN) diff --git a/Master/texmf-dist/doc/latex/pgfplots/Makefile b/Master/texmf-dist/doc/latex/pgfplots/Makefile index ab7aa8a5b89..6414fa5a278 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/Makefile +++ b/Master/texmf-dist/doc/latex/pgfplots/Makefile @@ -1,20 +1,22 @@ PDFLATEX=pdflatex -shell-escape -all: pgfplots.pdf pgfplotstable.pdf +all: pgfplots.pdf pgfplotstable.pdf TeX-programming-notes.pdf @echo "$^ have been compiled successfully. I did NOT check for references, so you may need to rerun make several times." +notes: TeX-programming-notes.pdf pgfplots: pgfplots.pdf pgfplotstable: pgfplotstable.pdf %.pdf: FORCE - @$(PDFLATEX) $(@:.pdf=.tex) + 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." clean: - rm -f *.aux *.ind *.idx *.toc *.out *.log *.ilg *.dvi pgfplots.pdf pgfplotstable.pdf *.djs *.bbl *.blg + rm -f *.aux *.ind *.idx *.toc *.out *.log *.ilg *.dvi pgfplots.pdf pgfplotstable.pdf *.djs *.bbl *.blg figures/expensiveexample* FORCE: diff --git a/Master/texmf-dist/doc/latex/pgfplots/README b/Master/texmf-dist/doc/latex/pgfplots/README deleted file mode 100644 index e0a52efb27b..00000000000 --- a/Master/texmf-dist/doc/latex/pgfplots/README +++ /dev/null @@ -1,36 +0,0 @@ -pgfplots - A tool to work with scientific data. It draws normal and/or -logarithmic plots in LaTeX/TeX/ConTeXt. - -pgfplotstable - Loads, rounds and formats and postprocesses numerical tables. - -Pgfplots draws high-quality function plots in normal or logarithmic -scaling with a user-friendly interface. The user supplies axis labels, legend -entries and the plot coordinates for one or more plots and Pgfplots applies -axis scaling, computes any logarithms and axis ticks and draws the plots. -It is based on Till Tantau's package PGF/TikZ. - -Pgfplotstable displays numerical tables rounded to desired precision in various -display formats, for example scientific format, fixed point format or integer, -using TeX's math facilities for pretty printing. - -Please take a look at - doc/latex/pgfplots/pgfplots.pdf -and - doc/latex/pgfplots/pgfplotstable.pdf. - - -Copyright 2007/2008 by Christian Feuersaenger. - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see <http://www.gnu.org/licenses/>. - diff --git a/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf b/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf Binary files differnew file mode 100644 index 00000000000..7657c60b10e --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.pdf diff --git a/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.tex b/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.tex new file mode 100644 index 00000000000..c675157b408 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.tex @@ -0,0 +1,659 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% Copyright 2007/2008 by Christian Feuersaenger. +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see <http://www.gnu.org/licenses/>. +% +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\input{pgfplots.preamble.tex} + +\usepackage{array} +\usepackage{colortbl} +\usepackage{booktabs} +\usepackage{eurosym} + +\long\def\codeexamplenl{\noexpand\par}% +\pgfqkeys{/codeexample}{% + every codeexample/.style={ + width=4cm, + /pgfplots/every axis/.append style={legend style={fill=graphicbackground}} + }, + narrow/.style={width=7cm}, + tabsize=4, + %pre={\begin{minipage}{\linewidth}\begingroup}, + %post={\endgroup\end{minipage}}, + vbox, + newline=\codeexamplenl, +} + +\title{Notes On Programming in \TeX}%\\and Library Functions from \PGF\ and \PGFPlots} + +\begin{document} +\maketitle +\begin{abstract}% + This document contains notes which are intended for those who are interested in \TeX\ programming. It is valueable for beginners as a first start with a lot of examples, and it is also valueable for experienced \TeX nicians who are interested in details about \TeX\ programming. However, it is neither a complete reference, nor a complete manual of \TeX. +\end{abstract} +\tableofcontents +\section{Introduction} +This document is intended to provide a direct start with \TeX\ programming (not necessarily \TeX\ typesetting). The addressed audience consists of people interested in package or library writing. + +At the time of this writing, this document is far from complete. Nevertheless, it might be a good starting point for interested readers. Consult the literature given below for more details. + +\section{Programming in \TeX} +\subsection{Variables in Registers} +\TeX\ provides several different variables and associated registers which can be manipulated freely. + +\label{sec:variables} +\begin{command}{\count\meta{num}} + There are 256 Integer registers which provide 32 Bit Integer arithmetics. The registers can be used for example with |\count0=42 | or |\count7=\macro | where |\macro| expands to a number. + + The value of a register can be typeset using |\the|\meta{register}. +\begin{codeexample}[] +\count0=42 +The value is now `\the\count0'. +\def\macro{-123456} +\count0=\macro +The value is now `\the\count0'. +\end{codeexample} + + The `|=|' sign is optional and can be omitted. One thing is common among the registers: an assignment of the form |\count0=|\meta{$\cdots$} expands everything which follows until the expansion doesn't need more numbers -- even more than one following macro. +\begin{codeexample}[] +\def\firstmacro{123} +\def\secondmacro{456} +\def\thirdmacro{789} +\count0=\firstmacro\secondmacro\thirdmacro +The value is now `\the\count0'. +\end{codeexample} + The precise rules can be found in~\cite{texbook}, but it should be kept in mind that care needs to be taken here. More than once, my code failed to produce the expected result because \TeX\ kept expanding macros and the registers got unexpected results. Here is the correct method: +\begin{codeexample}[] +1. \count0=42 % a white space after the number aborts the reading process. +The value is now `\the\count0'. +2. The following code will absorb the `3' of '3.': +\def\macro{1234} +\count0=\macro % a white space after a macro will be absorbed by TeX, so this is wrong. +3. The value is now `\the\count0'. +4. Use \textbackslash relax after an assignment to end scanning: +\count0=\macro\relax +5. The value is now `\the\count0'. +\end{codeexample} + The command |\relax| tells \TeX\ to ``relax'': it stops scanning for tokens, but |\relax| doesn't expand to anything. + \index{relax@\texttt{\textbackslash relax}}% +\end{command} + +\begin{command}{\dimen\meta{num}} + There are also 255 registers for fixed point numbers which are used pretty much in the same way as the |\count| registers -- but |\dimen| register assignments require a unit like `|cm|' or `|pt|'. + + String access with `|\the|' works in exactly the same way as for |\count| registers. +\begin{codeexample}[] +\dimen0=1pt +The value is now \the\dimen0. +\dimen0=0.0001pt +The value is now \the\dimen0. +\def\macro{1234.5678} +\dimen0=\macro pt +The value is now \the\dimen0. +\end{codeexample} + The same rules with expansion of macros after assignments apply here as well. + + The |\dimen| registers perform their arithmetics internally with 32 bit scaled integers, so called `scaled point' with unit `|sp|'. It holds |1sp=65536pt|=$2^{16}$|pt|. One of the 32 bits is used as sign. The total number range in |pt| is $[-(2^{30}-1)/2^{16}, (2^{30}-1)/2^{16} ] = [-16383.9998,+16383.9998]$\footnote{Please note that this does not cover the complete range of a 32 bit integer, I do not know why.}. +\end{command} + +\begin{command}{\toks\meta{number}} +\label{cmd:toks} + There are also 255 token registers which can be thought of as special string variables. Of course, every macro assignment |\def\macro|\marg{content} is also some kind of string variable, but token registers are special: their contents won't be expanded when used with |\the\toks|\meta{number}. This can be used for fine grained expansion control, see section~\ref{sec:expansion:control} below. +\end{command} + +\subsubsection{Allocating Registers} + +\subsubsection{Using More than 256 Registers} + +\subsection{Arithmetics in \TeX} +\begin{command}{\advance\meta{register}\texttt{ by}\meta{quantity}} +\begin{codeexample}[] +\count0=42 +\advance\count0 by 10 +The value is now \the\count0. +\end{codeexample} + +\begin{codeexample}[] +\dimen0=1pt +\advance\dimen0 by 10pt +The value is now \the\dimen0. +\end{codeexample} +\end{command} + +\begin{command}{\multiply\meta{register}\texttt{ by}\meta{integer}} +\begin{codeexample}[] +\count0=42 +\multiply\count0 by -10 +The value is now \the\count0. +\end{codeexample} + +\begin{codeexample}[] +\dimen0=0.5pt +\multiply\dimen0 by 20 +The value is now \the\dimen0. +\end{codeexample} +\end{command} + +\begin{command}{\divide\meta{register}\texttt{ by}\meta{integer}} + This allows integer division by \meta{integer} with truncation. +\begin{codeexample}[] +\count0=5 +\divide\count0 by 2 +The value is now \the\count0. +\end{codeexample} + + Scaling of |\dimen| registers: +\begin{codeexample}[] +\dimen0=10pt +\divide\dimen0 by 20 +The value is now \the\dimen0. +\end{codeexample} +\end{command} + +\begin{command}{\dimen\meta{number}\texttt{=}\meta{fixed point number without unit}\textbackslash dimen\meta{number}} + This allows fixed point multiplication in |\dimen| registers. +\begin{codeexample}[] +\dimen1=50pt +\dimen0=0.6\dimen1 +The value is now \the\dimen0. +\end{codeexample} +\end{command} + + +\subsection{Expansion Control} +\label{sec:expansion:control} +Expansion is what \TeX\ does all the time. Thus, expansion control is a key concept for understanding how to program in \TeX. + +The first thing to know is: \TeX\ deals the input as a long, long sequence of ``tokens''. A token is the smallest unit which is understood by \TeX. Each character becomes a token the first time it is seen by \TeX. Every macro becomes a (single!) token the first time it is seen by \TeX. + +The second thing to know is what characters are \emph{before} \TeX\ has seen them. Although this knowledge is rarely needed in every day's life, it is nevertheless important. The characters which are in the input document are nothing but characters at first. Even the characters known to have a special meaning like `|%|', `|\|' or the braces `|{}|' are \emph{not} special -- until they have been converted to a token. This happens when \TeX\ encounters them the first time during its linear processing of the character stream. A token stays a token - and it will remain the same token forever. If you manage to tell \TeX\ that `|\|' is a normal character and \TeX\ sees just one backslash, this backslash will be a normal character token -- even if the meaning of all following backslashes is again special. + +Now, we are given a very long list of tokens \meta{token1}\meta{token2}\meta{token3}\meta{token4}\meta{token5}$\cdots$. \TeX\ processes these tokens one-by-one in linear sequence. If \meta{token1} is a character token like `|a|', it is typeset. This is not what I want to write about here now; my main point is how to program in \TeX\footnote{Of course, typesetting is an art in itsself and there is a lot to read about it. Just not here in these notes.}. So, the interesting thing in these notes is when \meta{token1} is a macro. + +\subsubsection{Macros} +We have already seen some applications of macros above. Actually, most users who are willing to read notes about \TeX\ programming will have seen macros and may have written some on their own -- for example using |\newcommand| (|\newcommand| is a ``more high--level'' version of |\def| used only in \LaTeX). + +A macro has a name and is treated as an elementary token in \TeX\ (even if the name is very long). A macro has replacement text. As soon as \TeX\ encounters a macro, it replaces its occurance with the replacement text. Furthermore, a macro can consume one or more of the following tokens as arguments. +\begin{codeexample}[] +\def\macro{This here is actually the replacement text.} +Executing it: `\macro'. +\end{codeexample} +\begin{codeexample}[] +\def\macro#1{replacement with first argument=#1} +Invoking it: \macro{hello!}. +\end{codeexample} +This here is not really a surprise. What might come as a surprise is that the accepted arguments can be pretty much anything. +\begin{codeexample}[] +\def\macro#1-#2.{replacement with arguments: `#1' and `#2'.} +Invoking it: \macro a-sign. +\end{codeexample} +\noindent The last example |\macro| runs through the token list which follows the occurance of |\macro|. This token list is ``|a-sign.|''. Macro expansion is greedy, that means the first matching pattern is used. Now, our |\macro| expected something, then a minus sign `|-|', then another (possibly long) argument, then a period `|.|'. The argument between |\macro| and the minus sign is available as |#1| and the tokens between the minus sign and the period as |#2|. + +\begin{codeexample}[] +\def\macro(#1,#2,#3){I found arguments `#1', `#2' and `#3'.} +\macro(42,43,44) +\end{codeexample} + +As we have seen, macros can be used to manipulate the input tokens by expansion: they take some input arguments (maybe none) away and insert other tokens into the input token list. These tokens will be the next to process. We will soon learn more about that. + +There is a command which helps to understand what \TeX\ does here: + +\begin{command}{\meaning\meta{macro}} + This command expands to the contents of \meta{macro} as it is seen by \TeX. +\begin{codeexample}[] +\def\macro{Replacement \textmacro text \count0=42 \the\count0.} +\message{Debug message: '\meaning\macro'} +\end{codeexample} +As result, the log file and terminal output will contain + +|Debug message: 'macro:->Replacement \textmacro text \count 0=42 \the \count 0.'| +\end{command} + +The last example already shows something about |\def|: the replacement text can still contain other macros. + +\begin{command}{\def\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}} + A new macro named \meta{macroname} will be defined (or re-defined). The \marg{replacement text} is the macro body, whenever the macro is executed, it expands to \marg{replacement text}. The \marg{replacement text} is a token list which can contain other macros. On the time of the definition, \TeX\ does \emph{not} process (expand) the \marg{replacement text}. + + The \marg{replacement text} will only be expanded if the macro is executed. This does also apply to any macros which are inside of \marg{replacement text}. +\begin{codeexample}[] +\def\macroone{This is macro one} +\def\macrotwo{Macro two contains \macroone.} +Now, I execute it: \macrotwo. +\def\macroone{Redefined macroone} +Now, I exectute the second macro again: \macrotwo. +\end{codeexample} + + Macros can be defined almost everywhere in a \TeX\ document. They can also be invoked almost everywhere. + + The \meta{argument pattern} is a token list which can contain simple strings or macro parameters `|#|\meta{number}' or other macro tokens. The \meta{number} of the first parameter is always 1, the second must have 2 and so on up to at most 9. Valid argument patterns are `|#1#2#3|', `|(#1,#2,#3)|' or `|---\relax|'. If \TeX\ executes a macro, it searches for \meta{argument pattern} in the input token list until the first match is found. If no match can be found, it aborts with a (more or less helpful) error message. +\begin{codeexample}[] +\def\macroone abc{\macrotwo} +\def\macrotwo def{\macrothree} +\def\macrothree#1{Got `#1'} +\macroone abcdefg +\end{codeexample} + The last example contains three macro definitions. Then, \TeX\ encounters |\macroone|. The input token list is now + + `|\macroone abcdefg|'. + + The space(s) following |\macroone| are ignored by \TeX, they delimit the \meta{\textbackslash macroname}. Now, \TeX\ attempts to find matches for \meta{argument pattern}. It expects `|abc|' -- and it finds `|abc|'. These three tokens are \emph{removed} from the input token list, and \TeX\ inserts the replacement text of |\macroone| which is |\macrotwo|. At that time, the input token list is + + `|\macrotwo defg|'. + + Now, the same game continues with |\macrotwo|: \TeX\ searches for the expected \marg{argument pattern} which is `|def|', erases these tokens from the input token list and inserts the replacement text of |\macrotwo| instead. This yields + + `|\macrothree g|'. + + Finally, |\macrothree| expects one parameter token (or a token list enclosen in parenthesis). The next token is `|g|', which is consumed from the input token list and the replacement text is inserted -- and `|#1|' is replaced by `|g|'. Then, the token list is + + `|Got `g'|'. + + This text is finally typeset (because it doesn't expand further). +\end{command} + +What we have seen now is how \TeX\ macros can be used to modify the token list. It should be noted explicitly that macro expansion does is in no way limited to those tokens provided inside of \marg{replacement text} -- if the last argument in \marg{replacement text} is a macro which requires arguments, these arguments will be taken from the following tokens. Using nested macros, one can even process a complete part of the token list, in a manner of loops (but we don't know yet how to influence macro expansion conditionally, that comes later). + +Let's try to solve the following task. Suppose you have a macro named |\point| with \meta{argument pattern} `|(#1,#2)|', i.e. + +|\def\point(#1,#2){we do something with #1 and #2}|. + +\noindent +Suppose furthermore that you want to invoke |\point| with the contents which is stored in another macro. After all, macros are some kind of string variables -- it makes sense to accumulate or generate string variables which will then be used as input for other macros. Let's assume we have |\temp| and |\temp| contains `|(42,1234)|'. A first choice to invoke |\point| would be to use |\point\temp|. But: |\point| searches for an argument pattern which starts with `|(|', not with |\temp|! The invocation fails. + +\begin{command}{\expandafter\meta{token}\meta{next token}} + The |\expandafter| command is an -- at first sight confusing -- method to alter the input token list. But: it solves our problem with |\point\temp|! +\begin{codeexample}[] +\def\point(#1,#2){we do something with #1 and #2} +\def\temp{(42,1234)} +\expandafter\point\temp +\end{codeexample} + Why did that work!? The command |\expandafter| scans for the token after |\expandafter| in the input token list. This is |\point| in our case. Then, it scans for the next token which is |\temp| in our case (remember: macros are considered to be elementary tokens, just like characters `|a|' or so). The two scanned arguments are removed from the input token list. Then, |\expandafter| \emph{expands} the \meta{next token} one time. In our case, \meta{next token} is |\temp|. The first level of expansion of |\temp| is `|(42,1234)|'. Then, |\expansion| inserts the (unexpanded) \meta{token} followed by the (expanded) contents of \meta{next token} back into the input token list. In single steps: + + \begin{enumerate} + \item |\expandafter\point\temp| + \item Expand |\expandafter|: next two tokens are `|\point\temp|'. + \item Use |\point| as \meta{token} and |\temp| as \meta{next token}. + \item Expand |\temp| once, which leads to the tokens `|(42,1234)|'. + \item re-insert \meta{token} and the expansion of \meta{next token} back into the input token list. The list is then + + `|\point(42,1234)|'. + \item Expand |\point| as next token. + \end{enumerate} + + A further example: suppose we want to invoke |\theimportantmacro|\marg{argument}. However, \marg{argument} is contained in another macro! Furthermore, |\theimportantmacro| is defined to take exactly one parameter and our desired argument may have more than one token (which means we need to surround it with braces). This can be solved by the listing below. +\begin{codeexample}[] +\def\theimportantmacro#1{I got the pre-assembled argument `#1' here.} +\def\temp{xyz} +\expandafter\theimportantmacro\expandafter{\temp} +\end{codeexample} + Now, what happens here? Let's apply the rules step by step again: + \begin{enumerate} + \item After the initial definitions, the token list is |\expandafter\theimportantmacro\expandafter{\temp}|. + \item \TeX\ expands |\expandafter|, using |\theimportantmacro| as \meta{token} and the second |\expandafter| as \meta{next token}. + \item According to the rules, \TeX\ expands \meta{next token} once. But: \meta{next token} is again a macro, namely |\expandafter|! Does that make a difference? No: + \begin{enumerate} + \item The token list after the second |\expandafter| is `|{\temp}|' (3 tokens). + \item The \meta{token} is thus `|{|' and \meta{next token} is `|\temp|'. + \item The expansion of \meta{next token} is `|xyz|'. + \item The second |\expandafter| re-inserts its \meta{token} and expanded \meta{next token}, which is + + `|{xyz|'. + + Note that the closing brace `|}|' has not been touched at all, \TeX\ hasn't even seen it so far. + \end{enumerate} + We come back from the recursion. Remember: \meta{token} is |\theimportantmacro| and the top-level expansion of \meta{next token} is -- as we have seen above -- `|{xyz|'. + \item \TeX\ re-inserts \meta{token} and the expansion of \meta{next token} to the input token list, which leads to + + `|\theimportantmacro{xyz}|'. + + The closing brace `|}|' has not been touched, it simply resides in the input token list. + \item \TeX\ expands |\theimportantmacro|. + \end{enumerate} + + The \meta{next token} is expanded exactly once. We have already seen that if \meta{next token} is a macro which does substitutions on its own, these substitutions will be performed recursively. But what means `once' exactly? We will need to use |\meaning| to check that (or the |\tracingmacros| tools) because we need to see what \TeX\ does. +\begin{codeexample}[] +\def\macroone{This is macro one \macrotwo} +\def\macrotwo{--2--} +\def\macrothree#1{\def\macrofour{4[#1]}} +\expandafter\macrothree\expandafter{\macroone}% +So far, nothing has been typeset. But now: \macrofour. +\message{We have macrofour = \meaning\macrofour}% +\end{codeexample} + The logfile (and terminal) will now contain + + `|We have macrofour = macro:->4[This is macro one \macrotwo ]|'. + + What happened? We can proceed as in the last example. After the two |\expandafter| expansions, \TeX\ finds the input token list + + `|\macrothree{This is macro one \macrotwo}|' + + which, after execution, defines |\macrofour| to be `|This is macro one \macrotwo|'. The top-level expansion of |\macroone| has not expanded the nested call to |\macrotwo|. + + + So, |\expandafter| is a normal macro which can be expanded -- and it is even possible to expand an |\expandafter| by another |\expandafter|. +\end{command} + +What we have seen so far is +\begin{enumerate} + \item the |\def| command which stores \emph{unexpanded} arguments in a macro variable and + \item the |\expandafter| which allows control over top-level expansion of macros (it expands one time). +\end{enumerate} +\TeX\ provides two more features for expansion control: the |\edef| macro and token registers. + +\begin{command}{\edef\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}} + The |\edef| command is the same as |\def| insofar as it defines a new macro. However, it expands \marg{replacement text} until only unexpandable tokens remain (|\edef| $=$ expanded definition). +\begin{codeexample}[] +\def\a{3} +\def\b{2\a} +\def\c{1\b} +\def\d{value=\c} +\message{Macro `d' is defined to be `\meaning\d'} +\edef\d{value=\c} +\message{Macro `d' is e-defined to be `\meaning\d'} +\expandafter\def\expandafter\d\expandafter{\c} +\message{Macro `d' is defined to be `\meaning\d' using expandafter} +\end{codeexample} + This listing results in the log-file output + + |Macro `d' is defined to be `macro:->value=\c '| + + |Macro `d' is e-defined to be `macro:->value=123'| + + |Macro `d' is defined to be `macro:->1\b ' using expandafter| + + \noindent So, |\def| does not expand at all, |\edef| expands until it can't expand any further and the |\expandafter| construction expands |\c| one time and defines |\d| to be the result of this expansion. + + Although possible, it might not occur too often to specify \meta{argument pattern} for an |\edef| because the expansion is immediate in contrast to |\def|. But it works in the same way: the positional arguments |#1|, |#2|$,\dotsc,$ |#9| will be replaced with their arguments. + + The expansion of \marg{replacement text} happens in the same way as the expansion the main token list of \TeX. + + Now, what exactly does ``expands until only unexpandable tokens remain'' mean? Our example indicates that the three tokens |1|, |2| and |3| are not expandable while the macros |\c|, |\b| and |\a| could be expanded. There is one large class of \TeX\ commands which can't be expanded: any assignment operation. The example +\begin{codeexample}[] +\edef\d{\count0=42} +\message{Macro `d' is defined to be `\meaning\d'} +\def\a{1234} +\edef\d{\advance\count0 by\a} +\message{Macro `d' is defined to be `\meaning\d'} +\end{codeexample} +\noindent yields the log-messages + +|Macro `d' is defined to be `macro:->\count 0=42'| and + +|Macro `d' is defined to be `macro:->\advance \count 0 by1234'|. + +So, assignment and arithmetics operations are \emph{not} expandable, they remain as executable tokens in the newly defined macro. This does also hold for |\let| and other assignment operations. + + Interestingly, conditional expressions using |\if| $\dotsb$ |\fi| \emph{are} expandable, but we will come to that later. + + There is also a method to convert a macro temporarily into an unexpandable token: the |\noexpand| macro. +\end{command} + +\begin{command}{\noexpand\meta{expandable token}} + The |\noexpand| command is only useful inside of the \marg{replacement text} of an |\edef| command. As soon as |\edef| encounters the |\noexpand|, the |\noexpand| will be removed and the \meta{expandable token} will be converted into an unexpandable token. Thus, the code +\begin{codeexample}[] +\edef\d{Invoke \noexpand\a another macro} +\message{Macro `d' is defined to be `\meaning\d'} +\end{codeexample} +\noindent yields the terminal output + +|Macro `d' is defined to be `macro:->Invoke \a another macro'| + +because |\noexpand\a| yields the token `|\a|' (unexpanded)\footnote{The \texttt{\textbackslash noexpand} key is actually used to implement the \LaTeX\ command \texttt{\textbackslash protect}: \LaTeX's concept of moveable arguments is implemented with \texttt{\textbackslash edef}.}. +\end{command} + +\subsubsection{Token Registers} +Now, we turn to token registers. As we have already seen in section~\ref{cmd:toks}, a token register stores a token list. A macro does also store a token list in its \marg{replacement text}, so where is the difference? There are two differences: +\begin{enumerate} + \item Token registers are faster. + \item The contents of token registers will \emph{never} be expanded. +\end{enumerate} +I can't give numbers for the first point -- I have just read it in~\cite{texbook}. But the second point allows expansion control. While |\edef| allows ``infinite'' expansion, token registers allow only top--level expansion, just like |\expandafter|. But they can be used in a more flexible (and often more efficient) way than |\expandafter|. + +The following examples demonstrates the second point. +\begin{codeexample}[] +\toks0={A \token list \a \b \count0=42 will never be expanded} +\edef\d{\the\toks0 }% the space token is important! +\message{Macro `d' is defined to be `\meaning\d'} +\end{codeexample} +\noindent Executing this code fragment yields the log output + +|Macro `d' is defined to be `macro:->A \token list \a \b \count 0=42 will never be expanded'|. + +So, the contents of |\toks0| has been copied unexpanded into |\d|, although we have just |\edef|. Note that the space token after |\the\toks0| is indeed important! \TeX\ uses it to delimit the integer |0|. Without the space token, it would have continued scanning, even beyond the boundaries of the replacement text of |\edef| (see section~\ref{sec:variables} for details about this scanning). + +The example is very simple, and we could have done the same with |\expandafter| as before. But let's try something more difficult: we want to assemble a new macro which consists of different pieces. Each piece is stored in a macro, and for whatever reason, we only want top-level expansion of the single pieces. And: the pieces won't be adjacent to each other. We can assemble the target macro using the following example listing. + +\begin{codeexample}[] +\def\piecea{\a{xyz}} +\def\pieceb{\count0=42 } +\def\piecec{string \b} +\toks0=\expandafter{\piecea} +\toks1=\expandafter{\pieceb} +\toks2=\expandafter{\piecec} +\edef\d{I have \the\toks0 and \the\toks1 and \the\toks2} +\message{Macro `d' is defined to be `\meaning\d'} +\end{codeexample} + +The first three lines define our pieces. Each of the macros |\piecea|, |\pieceb| and |\piecec| contains tokens which should not be expanded during the definition of |\d|. The three following lines assign the top-level expansion of our pieces into token registers. Since |\toks0={\piecea}| would have stored `|\piecea|' into the token register, we need to use |\expandafter| here\footnote{We could have eliminated the \texttt{\textbackslash piece*} macros by writing everything into token registers directly. But I think this example is more realistic.}. Then, we use |\the\toks|\meta{number} to insert the contents of a token list somewhere -- in our case, into the expanded replacement text of our macro |\d|. Thus, the complete example yields the log--output + +|Macro `d' is defined to be `macro:->I have \a {xyz}and \count 0=42 and string \b '|. + +\noindent It \emph{is} possible to get exactly the same result using (a lot of) |\expandafter|s. Don't try it. + + +\subsubsection{Summary of macro definition commands} +Besides |\def| and |\edef|, there are some more commands which allow to define macros (although the main functionality is covered by |\def| and |\edef|). Here are the remaining definition commands. +\begin{command}{\def\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}} + Defines a new macro named |\macroname| without expanding \marg{replacement text}, see above. +\end{command} +\begin{command}{\edef\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}} + Defines a new macro named |\macroname|, expanding \marg{replacement text} completely (see above). +\end{command} +\begin{command}{\let\meta{\textbackslash newmacro}=\meta{token}} + Defines or redefines |\newmacro| to be an equivalent to \meta{token}. For example, |\let\a=\b| will create a new copy of macro |\b|. The copy is named |\a|, and it will have exactly the same \marg{replacement text} and \meta{argument pattern} as |\b|. + + It is also possible that \meta{token} is something different than a macro, for example a named register or a single character. +\end{command} + +\begin{command}{\gdef\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}} + A shortcut for |\global\def|. It defines |\macroname| globally, independant of the current scope. + + You should avoid macros which exist in both, the global namespace and a local scope, with different meanings. Section~\ref{sec:scopes} explains more about scoping. +\end{command} +\begin{command}{\xdef\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}} + A shortcut for |\global\edef|. It defines |\macroname| globally, independant of the current scope. + + You should avoid macros which exist in both, the global namespace and a local scope, with different meanings. Section~\ref{sec:scopes} explains more about scoping. +\end{command} + +\begin{command}{\csname\meta{expandable tokens}\textbackslash endcsname} + This command is not a macro definition, it is a definition of a macro's \emph{name}. The ``cs'' means ``control sequence''. The |\csname|, |\endcsname| pair defines a control sequence name (a macro name) using \meta{expandable tokens}. The control sequence character `|\|' will be prepended automatically by |\csname|.\footnote{In fact, the contents of \texttt{\textbackslash escapechar} will be used here. If its value is -1, no character will be prepended. The same holds for any occurance where a backslash would be inserted by \TeX\ commands.} +\begin{codeexample}[] +\def\macro{Content} +This here is normal usage: `\macro'. +This here uses csname: `\csname macro\endcsname'. +\end{codeexample} + \noindent The example demonstrates that |\csname|\meta{expandable tokens}|\endcsname| is actually the same as if you had written |\|\meta{expandable tokens} directly -- but the |\csname| construction allows much more tokens inside of macro names: +\begin{codeexample}[] +\expandafter\def\csname a01macro with.strange.chars\endcsname{Content} +I use a strange macro. Here is it: `\csname a01macro with.strange.chars\endcsname'. +\end{codeexample} + \noindent The example uses |\expandafter| to expand |\csname| one time. The top--level expansion of |\csname| is a single token, namely the control sequence name. Then, |\def| is used to define a macro with the prepared macro name. + + When |\csname| is expanded, it parses all tokens up to the next |\endcsname|. Those tokens will be expanded until only unexpandable tokens remain (as in |\edef|). The resulting string will be used to define a macro name (with the control sequence character `|\|' prepended). The fact that \meta{expandable tokens} is expanded allows to use ``indirect'' macro names: +\begin{codeexample}[] +\def\macro{onetwothree} +\expandafter\def\csname macro\macro\endcsname{Content} +I have just defined \expandafter\string\csname macro\macro\endcsname +with replacement text `\csname macro\macro\endcsname'. +\end{codeexample} + \noindent I suppose the example is self-explaining, up to the |\string| command which is described below. + + Due do this flexibility, |\csname| is used to implement all (?) of the available key--value packages in \TeX. +\end{command} + +\begin{command}{\string\meta{\textbackslash macro}} + This command does not define a macro. Instead, it returns a macro's name as a sequence of separate tokens, including the control sequence token `|\|'. +\begin{codeexample}[] +\def\macro{Content} +I have just defined `\string\macro' using `\string\def'. +\end{codeexample} + + You can also use |\string| on other tokens -- for example characters. That doesn't hurt, the character will be returned as-is. +\end{command} + +\subsubsection{Debugging Tools -- Understanding and Tracing What \TeX\ Does} +\begin{command}{\message\marg{tokens}} +\end{command} +\begin{command}{\meaning\meta{\textbackslash macro}} +\end{command} +\begin{command}{\tracingmacros=2} +\end{command} +\begin{command}{\tracingcommands=2} +\end{command} +\begin{command}{\tracingrestores=1} +\end{command} + +\subsection{The Scope of a Variable} +\label{sec:scopes} +Each programming language knows the concept of a scope: they limit the effect of variables or routines. However, \TeX's scoping mechanisms have not been designed for programming -- \TeX\ is a typesetting language. Many programming languages like |C|, |C++|, |java| or a lot of scripting languages define the scope of a variable using the place where the variable has been defined. For example, the |C| fragment +\begin{codeexample}[code only] +int i = 42; + +{ + ++i; + int i = 5; +} +\end{codeexample} +\noindent changes the value of the outer |i| to |43|. The inner |i| is |5|, but it will be deleted as soon as the closing brace is encountered. It may even be possible to access both, the value of the inner |i| variable and the value of the outer |i| variable, at the same time. + +In \TeX, braces are also used for scopes. But: while \TeX\ will also destroy any variables (macros) defined inside of a scope at the end of that scope, it will \emph{also} undo any change which has been applied inside of that scope. +\begin{codeexample}[] +\def\i{42} +{ + \def\i{43} + \def\b{2} +} +The value of \textbackslash i is now \i. +\end{codeexample} +\noindent The listing above defines |\i|, enters a local scope (a \TeX\ ``group'') and changes |\i|. However, due to \TeX's scoping rules, the old program state will be restored \emph{completely} after returning from the local group! Neither the change to |\i| nor the definition of |\b| will survive. The same holds for register changes or other assignments. + +\TeX\ groups can be created in one of three ways: using curly braces\footnote{Or other tokens with the correct category code, compare~\cite{texbook}.}, using |\begingroup| or using |\bgroup|. Curly braces are seldom used to delimit \TeX\ groups because the other commands are more flexible. If one uses curly braces, they need to match up -- it is forbidden to have unmatches curly braces. +\begin{command}{\begingroup} + Starts a new \TeX\ group (a local scope). The scope will be active until it will be closed by |\endgroup|. The |\endgroup| command can occur later in the main token list. +\end{command} +\begin{command}{\endgroup} + Ends a \TeX\ group which has been opened with |\begingroup|. +\end{command} +\begin{command}{\bgroup} + A special variant of |\begingroup| which can also be used to delimit arguments to |\hbox| or |\vbox| (i.e. it avoids the necessity to provide matched curly braces in this context). + + The |\bgroup| macro is also useful to test whether the next following character is an opening brace (see |\futurelet|). + + If one just needs to open a \TeX\ group, one should prefer |\begingroup|. +\end{command} +\begin{command}{\egroup} + Closes a preceding |\bgroup|. +\end{command} + +\TeX\ does not know how to write into macros of an outer scope -- except for the topmost (global) scope. This restriction is quite heavy if one needs to write complex structures: local variables should be declared inside of local groups, but changes to the structure should be written to the outer group. There is no direct possibility to do such a thing (except global variables). + +\subsubsection{Global Variables} +\TeX\ knows only ``global'' variables and ``local'' variables. A local variable will be deleted at the end of the group in which it has been declared. All values assigned locally will also be restored to their old value at the end of the group. + +A global variable, on the other hand, maintains the same value throughout \emph{every} scope. Usually, the topmost scope is the same as the one used for global variables: if you define anything in your \TeX\ document, you add commands on global scope. It is also possible to explicitly make assignments or definitions in the global scope. + +\begin{command}{\global\meta{definition or assignment}} + The definition which follows |\global| immediately will be done globally. +\begin{codeexample}[code only] +{ + \global\def\a{123} + \global\advance\count0 by3 + \global\toks0={34} +} +\end{codeexample} +\end{command} + +\begin{command}{\globaldefs=\mchoice{-1,0,1} (initially 0)} + I cite from~\cite{texbook}: ``If the |\globaldefs| parameter is positive at the time of an assignment, a prefix of |\global| is automatically implied; but if |\globaldefs| is negative at the time of the assignment, a prefix of |\global| is ignored. If |\globaldefs| is zero (which it usually is), the appearance of nonappearance of |\global| determines whether or not a global assignment is made.'' +\end{command} + + +\subsubsection{Transporting Changes to an Outer Group} +There are a couple of methods to ``transport'' changes to an outer scope. Some are copy operations, some require to redo the the changes again after the end of the scope. All of them can be realized using expansion control. + +Let's start with macro definitions which should be carried over the end of the group. I see the following methods: +\begin{itemize} + \item Copy the macro into a global, temporary variable (or even token register) and get that value after the scope. +\begin{codeexample}[code only] +\def\initialvalue{0} +{ + % do something: + \def\initialvalue{42} + \global\let\myglobaltemporary=\initialvalue +} +\let\initialvalue=\myglobaltemporary +\end{codeexample} + The idea is that |\myglobaltemporary| is only used temporary; its value is always undefined and can be overwritten at any time. This allows to use a local variable |\initialvalue|. + + Please note that you should not use variables both globally and locally. This confuses \TeX\ and results in a slow-down at runtime. + + \item ``Smuggle'' the result outside of the current group. I know this idea from the implementation of~\cite{tikz} written by Mark Wibrow and Till Tantau. The idea is to use several |\expandafter|s and a |\def| to redefine the macro directly after the end of the group: +\begin{codeexample}[code only] +\def\smuggle#1\endgroup{% + \expandafter\endgroup\expandafter\def\expandafter#1\expandafter{#1}% +} + +\begingroup + \def\variable{12} + \edef\variable{\variable34} + \edef\variable{\variable56} + \smuggle\variable +\endgroup +\end{codeexample} + The technique relies on groups started with |\begingroup| and ended with |\endgroup| because unmatched braces are not possible with |\def|. The effect is that after all those |\expandafter|s, \TeX\ encounters the token list + + |\endgroup\def\variable{123456}| + + at the end of the group. + + \item Use the aftergroup stack. \TeX\ has a special token stack of limited size which can be used to re-insert tokens after the end of a group. However, this does only work efficiently if the number of tokens which need to be transported is small and constant (say, at most three). It works by prefixing every token with |\aftergroup|, compare~\cite{texbook} for details. +\end{itemize} + +Sometimes one needs to copy other variables outside of a scope. The trick with a temporary global variable works always, of course. But it is also possible to define a macro which contains commands to apply any required changes and transport that macro out of the scope. + +\subsection{More On \TeX} +This document is far from complete. I recommend reading about conditional expressions in \cite{schwartz} (german, online version) or \cite{texbook} (bounded book). Hints about loops can be found in the manual of \PGFPlots, \cite{pgfplots} and the manual of \PGF, \cite{tikz}. Moreover, \PGFPlots\ and \PGF\ come with a whole lot of utility functions which are documented in the source |.code.tex| files. + +%\subsection{Conditional Expressions} + +%\subsection{Loops} + +%\subsection{The Problem of Macro--Append Runtime} + +%\section{Utility Functions of \PGF} + +%\section{Utility Function of \PGFPlots} + +\printindex + +\bibliographystyle{abbrv} %gerapali} %gerabbrv} %gerunsrt.bst} %gerabbrv}% gerplain} +\nocite{schwartz} +\nocite{pgfplots} +\bibliography{pgfplots} +\end{document} diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig1.png b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig1.png Binary files differindex 1304cf23291..af18e37dabd 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig1.png +++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig1.png diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig2.png b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig2.png Binary files differindex 873a372dd73..446a25616e1 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig2.png +++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig2.png diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig3.png b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig3.png Binary files differindex 79b4d2fe0ff..44a0cc17e97 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig3.png +++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig3.png diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig4.png b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig4.png Binary files differindex 636f307f42a..c72f79ac85c 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig4.png +++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable-fig4.png diff --git a/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable.tex b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable.tex new file mode 100644 index 00000000000..2bf3609b914 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/figures/pgfplotsclickable.tex @@ -0,0 +1,34 @@ +\documentclass[a4paper]{article} + +\usepackage{pgfplots} +\pgfplotsset{compat=newest} +\usepgfplotslibrary{clickable} + +\begin{document} +\begin{tikzpicture} + \begin{axis}[xlabel=$x$,ylabel=$y$, + domain=-2:2, + samples=17, + legend style={at={(0.5,0.98)},anchor=north,legend columns=-1} + ] + \addplot {x}; + \addplot {x^2}; + \addplot {x^3}; + \legend{$x$,$x^2$,$x^3$} + \end{axis} +\end{tikzpicture} + +\begin{tikzpicture} + \begin{semilogyaxis}[ + xlabel=$x$,ylabel=$f(x)$, + samples=10, + domain=0:6, + legend style={at={(0.5,0.98)},anchor=north,legend columns=-1} + ] + \addplot {exp(x)}; + \addplot {10^x}; + \legend{$\exp(x)$,$10^x$} + \end{semilogyaxis} +\end{tikzpicture} +\end{document} + diff --git a/Master/texmf-dist/doc/latex/pgfplots/gallery/Makefile b/Master/texmf-dist/doc/latex/pgfplots/gallery/Makefile new file mode 100644 index 00000000000..f65f03818db --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gallery/Makefile @@ -0,0 +1,39 @@ +# converts all examples from pgfplots and pgfplotstable to graphics and assembles a pretty-printed HTML gallery. +# +# +# REQUIREMENTS: +# make sure TEXINPUTS contains the doc/latex/pgfplots/ tree recursively. + +DOC_SRC=$(wildcard ../pgfplots.*.tex) ../pgfplotstable.tex +# DOC_SRC:=../pgfplotstable.tex + +PREPARED_SRC=$(wildcard example*.tex) + +.PHONY: all clean prepared + +all: prepare + $(MAKE) prepared + $(MAKE) images + +prepare: $(DOC_SRC) + ./extractexamples.pl ./example ./index.html $(DOC_SRC) + touch $@ + +clean: + rm ./example* prepare index.html + + +prepared: $(PREPARED_SRC:%.tex=%.pdf) + +images: $(PREPARED_SRC:%.tex=%.png) + +%.png: %.pdf + convert -transparent white -depth 150 $< $@ + +# eliminate the %.tex dependency to simplify remakes: +# %.pdf: %.tex + +%.pdf: + export TEXINPUTS="$(TEXINPUTS)..:../figures:" && pdflatex -interaction batchmode -halt-on-error -shell-escape $(@:.pdf=) 2>/dev/null 1>/dev/null + pdfcrop $@ $@ 2>/dev/null 1>/dev/null + @rm $(@:.pdf=.log) $(@:.pdf=.aux) diff --git a/Master/texmf-dist/doc/latex/pgfplots/gallery/extractexamples.pl b/Master/texmf-dist/doc/latex/pgfplots/gallery/extractexamples.pl new file mode 100644 index 00000000000..b58e8f00817 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gallery/extractexamples.pl @@ -0,0 +1,205 @@ +#!/usr/bin/perl -w +# +# A script +# extractexamples.pl <PREFIX> <htmlfilename> <INFILES> +# which +# - processes every input .tex file +# - extracts all tikzpicture-environments which are inside of a codeexample +# - generates <PREFIX>_<index>.tex +# - writes an index-html file into <htmlfilename> +# +# Furthermore, it processes every LaTeX Comment which is DIRECTLY before the codeexample to export: +# +# % \usepackage{array} +# \begin{codeexample}[] +# \begin{tikzpicture} +# ... +# +# will be interpreted as required preamble-information for the gallery. Thus, +# \usepackage{array} will be included into the particular output file. +# +# See the associated Makefile which also exports each thing into pdf and png. + + +sub maskForHTML { + my $arg = $_[0]; +# $arg =~ s/ + return $arg; +} + +$#ARGV > 0 or die('expected OUTPREFIX OUTHTML INFILE[s].'); + +$OUTPREFIX=$ARGV[0]; +$OUTHTMLNAME=$ARGV[1]; + +$header = +'\documentclass{article} +% translate with >> pdflatex -shell-escape <file> + +% This file is an extract of the PGFPLOTS manual, copyright by Christian Feuersaenger. +% +% Feel free to use it as long as you cite the pgfplots manual properly. +% +% See +% http://pgfplots.sourceforge.net/pgfplots.pdf +% for the complete manual. +% +% Any required input files (for <plot table> or <plot file> or the table package) can be downloaded +% at +% http://www.ctan.org/tex-archive/graphics/pgf/contrib/pgfplots/doc/latex/ +% and +% http://www.ctan.org/tex-archive/graphics/pgf/contrib/pgfplots/doc/latex/plotdata/ + +\usepackage{pgfplots} + +\pagestyle{empty} +'; + +$plotcoord_cmd=' +% \addplot table[x=dof,y=L2error] {d2data.dat}; +\addplot coordinates { +(5,8.312e-02) (17,2.547e-02) (49,7.407e-03) +(129,2.102e-03) (321,5.874e-04) (769,1.623e-04) +(1793,4.442e-05) (4097,1.207e-05) (9217,3.261e-06) +}; + +% \addplot table[x=dof,y=L2error] {d3data.dat}; +\addplot coordinates{ +(7,8.472e-02) (31,3.044e-02) (111,1.022e-02) +(351,3.303e-03) (1023,1.039e-03) (2815,3.196e-04) +(7423,9.658e-05) (18943,2.873e-05) (47103,8.437e-06) +}; + +% \addplot table[x=dof,y=L2error] {d4data.dat}; +\addplot coordinates{ +(9,7.881e-02) (49,3.243e-02) (209,1.232e-02) +(769,4.454e-03) (2561,1.551e-03) (7937,5.236e-04) +(23297,1.723e-04) (65537,5.545e-05) (178177,1.751e-05) +}; + +% \addplot table[x=dof,y=L2error] {d5data.dat}; +\addplot coordinates{ +(11,6.887e-02) (71,3.177e-02) (351,1.341e-02) +(1471,5.334e-03) (5503,2.027e-03) (18943,7.415e-04) +(61183,2.628e-04) (187903,9.063e-05) (553983,3.053e-05) +}; + +% \addplot table[x=dof,y=L2error] {d6data.dat}; +\addplot coordinates{ +(13,5.755e-02) (97,2.925e-02) (545,1.351e-02) +(2561,5.842e-03) (10625,2.397e-03) (40193,9.414e-04) +(141569,3.564e-04) (471041,1.308e-04) +(1496065,4.670e-05) +}; +'; + +$i = 0; +open OUTHTML,'>',$OUTHTMLNAME or die('could not open $OUTHTMLNAME for writing.'); +print OUTHTML +'<html> +<head> + <link rel="stylesheet" type="text/css" href="gallery.css"> +</head> +<body> +<h2>PGFPlots Gallery</h2> +<h4>The following graphics have been generated with the LaTeX Packages <a href="http://pgfplots.sourceforge.net/pgfplots.pdf">PGFPlots</a> and <a href="http://pgfplots.sourceforge.net/pgfplotstable.pdf">PGFPlotsTable</a>.</h4> +'; + +for($j = 2; $j<=$#ARGV; ++$j ) { + open FILE,$ARGV[$j] or die("could not open ".$ARGV[$j]); + + @S = stat(FILE); + $fileSize = $S[7]; + read(FILE,$content,$fileSize) or die("could not read everything"); + close(FILE); + + $autoheaders = ''; + $largegraphics = 0; + + @matches = ( $content =~ m/(% [^\n]*\n)*([^\n]*)\\begin{codeexample}(\[[^\n]*\])\n(.*?)[\n \t]*\\end{codeexample}/gs ); + # @matches = ( $content =~ m/(% [^\n]*\n)*\\begin{codeexample}(\[\])\n(\\begin{tikzpicture}.*?\\end{tikzpicture})/gs ); + + if( $ARGV[$j] =~ m/pgfplotstable.tex/ ) { + $largegraphics = 1; + $autoheaders = ' +\usepackage{array} +\usepackage{colortbl} +\usepackage{booktabs} +\usepackage{eurosym} +\usepackage{amsmath} +'; + } + + for( $q=0; $q<=$#matches/4; $q++ ) { + $prefix = $matches[4*$q]; + $prefix = "" if not defined($prefix); + next if ($prefix =~ m/NO GALLERY/); + $prefix =~ s/% //; + + $possiblecomment = $matches[4*$q+1]; + $possiblecomment = "" if not defined($possiblecomment); + next if ($possiblecomment =~ m/%/); + + $codeexamplearg= $matches[4*$q+2]; + $match = $matches[4*$q+3]; + + # Make sure we have only "relevant" pictures: + next if not ($match =~ m/tikzpicture.*(axis|semilogxaxis|semilogyaxis|loglogaxis).*\\addplot|pgfplotstabletypeset/s); + + # no complete examples: + next if ($match =~ m/\\begin{document}/); + + $match =~ s/\\plotcoords/$plotcoord_cmd/o; + + if ( ($codeexamplearg =~ m/code only/) ) { + print OUTHTML "<div class=\"img\">\n"; + print OUTHTML "\t<div class=\"codeonly\">".maskForHTML($match)."</div>\n"; + print OUTHTML "</div>\n"; + + } else { + $outfile = $OUTPREFIX."_".($i++).".tex"; + # print "$i PREFIX: ".$prefix."\n"; + # print "$i : ".$match."\n\n"; + # next; + open(OUTFILE,">",$outfile) or die( "could not open $outfile for writing"); + print OUTFILE $header; + print OUTFILE $autoheaders; + print OUTFILE $prefix; + print OUTFILE "\n\\begin{document}\n"; + print OUTFILE $match; + print OUTFILE "\n\\end{document}\n"; + close(OUTFILE); + + $png = $outfile; + $png =~ s/.tex/.png/; + $pdf = $outfile; + $pdf =~ s/.tex/.pdf/; + print OUTHTML "<div class=\"img\">\n"; + if( $largegraphics ) { + print OUTHTML "\t<span class=\"largegraphics\">\n"; + print OUTHTML "\t\t<a class=\"texlink_from_image\" href=\"".$pdf."\"><img src=\"".$png."\"/></a><br/>\n"; + print OUTHTML "\t\t<a class=\"texlink\" href=\"".$outfile."\">[.tex]</a>\n"; + print OUTHTML "\t\t<a class=\"pdflink\" href=\"".$pdf."\">[.pdf]</a>\n"; + print OUTHTML "\t</span>\n"; + print OUTHTML "\t<div class=\"codeonly\">".maskForHTML($match)."</div>\n"; + print OUTHTML "</div>\n"; + } else { + print OUTHTML "\t<span class=\"graphics\">\n"; + print OUTHTML "\t\t<a class=\"texlink_from_image\" href=\"".$pdf."\"><img src=\"".$png."\"/></a><br/>\n"; + print OUTHTML "\t\t<a class=\"texlink\" href=\"".$outfile."\">[.tex]</a>\n"; + print OUTHTML "\t\t<a class=\"pdflink\" href=\"".$pdf."\">[.pdf]</a>\n"; + print OUTHTML "\t</span>\n"; + print OUTHTML "\t<div class=\"texsrc\">".maskForHTML($match)."</div>\n"; + print OUTHTML "</div>\n"; + } + } + } + +} +print OUTHTML +'</body> +</html> +'; +close OUTHTML; +print "Exported ".$i." examples.\n"; +exit 0; diff --git a/Master/texmf-dist/doc/latex/pgfplots/gallery/gallery.css b/Master/texmf-dist/doc/latex/pgfplots/gallery/gallery.css new file mode 100644 index 00000000000..ed34d39ee53 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gallery/gallery.css @@ -0,0 +1,74 @@ + +div.img { + vertical-align:top; + margin-top:20px; + margin-bottom:20px; +} + +div img { + /* + * float:left; + */ + margin-left:20px; + margin-right:20px; +} + +.img .graphics { + width:300px; + display:inline-block; + text-align:right; + background-color:#f5f5cc; + padding-top:10px; + padding-bottom:10px; +} +.img .largegraphics { + width:850px; + display:inline-block; + text-align:left; + background-color:#f5f5cc; + padding:10px; +} +.codeonly { + display:inline-block; + white-space:pre; + font-family:monospace; + padding:10px; + background-color:#ccccff; + width:850px; +} + +.img .texlink { + color:black; +} +.img .pdflink { + margin-right:15px; + color:black; +} + +.img * { + vertical-align:top; + border-spacing:0px; + border-style:none; + outline-style:none; + text-decoration:none; +} +.img a:link { text-decoration:none; } +.img a:visited { text-decoration:none; } +.img a:hover { text-decoration:none; } +.img a:active { text-decoration:none; } +.img a:focus { text-decoration:none; } + +.img a:hover { + border-style:none; + text-decoration:none; +} + +.texsrc { + margin-left:10px; + display:inline-block; + white-space:pre; + font-family:monospace; + padding:10px; + background-color:#ccccff; + width:530px; +} diff --git a/Master/texmf-dist/doc/latex/pgfplots/gallery/pgfshell_cos.sh b/Master/texmf-dist/doc/latex/pgfplots/gallery/pgfshell_cos.sh new file mode 100644 index 00000000000..69dfb98cfb0 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gallery/pgfshell_cos.sh @@ -0,0 +1 @@ +awk 'BEGIN{ pi=3.14159; N=10; for(i=0;i<=N;i++) print i,cos(i/N*pi);}' diff --git a/Master/texmf-dist/doc/latex/pgfplots/gallery/pgfshell_replot.sh b/Master/texmf-dist/doc/latex/pgfplots/gallery/pgfshell_replot.sh new file mode 100644 index 00000000000..43f9c74b10d --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gallery/pgfshell_replot.sh @@ -0,0 +1 @@ +cat pgfshell_cos.out diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_DoG.gnuplot b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_DoG.gnuplot new file mode 100644 index 00000000000..722f1b2926b --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_DoG.gnuplot @@ -0,0 +1,2 @@ +set table "gnuplot/pgfplots_DoG.table"; set format "%.5f" +set format "%.7e";; set samples 100; plot [x=-15:15] 1.3*exp(-x**2/10) - exp(-x**2/20); diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_DoG.table b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_DoG.table new file mode 100644 index 00000000000..d0bc6aa2934 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_DoG.table @@ -0,0 +1,104 @@ + +#Curve 0 of 1, 100 points +#x y type +-1.5000000e+01 -1.3007078e-05 i +-1.4696970e+01 -2.0398026e-05 i +-1.4393939e+01 -3.1696136e-05 i +-1.4090909e+01 -4.8801505e-05 i +-1.3787879e+01 -7.4450441e-05 i +-1.3484848e+01 -1.1253984e-04 i +-1.3181818e+01 -1.6855715e-04 i +-1.2878788e+01 -2.5014140e-04 i +-1.2575758e+01 -3.6780325e-04 i +-1.2272727e+01 -5.3583245e-04 i +-1.1969697e+01 -7.7341929e-04 i +-1.1666667e+01 -1.1060098e-03 i +-1.1363636e+01 -1.5669021e-03 i +-1.1060606e+01 -2.1990684e-03 i +-1.0757576e+01 -3.0571566e-03 i +-1.0454545e+01 -4.2095735e-03 i +-1.0151515e+01 -5.7404907e-03 i +-9.8484848e+00 -7.7515264e-03 i +-9.5454545e+00 -1.0362753e-02 i +-9.2424242e+00 -1.3712560e-02 i +-8.9393939e+00 -1.7955780e-02 i +-8.6363636e+00 -2.3259361e-02 i +-8.3333333e+00 -2.9794790e-02 i +-8.0303030e+00 -3.7726479e-02 i +-7.7272727e+00 -4.7195413e-02 i +-7.4242424e+00 -5.8297668e-02 i +-7.1212121e+00 -7.1057888e-02 i +-6.8181818e+00 -8.5398571e-02 i +-6.5151515e+00 -1.0110702e-01 i +-6.2121212e+00 -1.1780296e-01 i +-5.9090909e+00 -1.3491113e-01 i +-5.6060606e+00 -1.5164422e-01 i +-5.3030303e+00 -1.6700223e-01 i +-5.0000000e+00 -1.7979430e-01 i +-4.6969697e+00 -1.8868807e-01 i +-4.3939394e+00 -1.9228931e-01 i +-4.0909091e+00 -1.8925117e-01 i +-3.7878788e+00 -1.7840774e-01 i +-3.4848485e+00 -1.5892178e-01 i +-3.1818182e+00 -1.3043157e-01 i +-2.8787879e+00 -9.3178121e-02 i +-2.5757576e+00 -4.8092850e-02 i +-2.2727273e+00 3.1731498e-03 i +-1.9696970e+00 5.8291956e-02 i +-1.6666667e+00 1.1437994e-01 i +-1.3636364e+00 1.6819310e-01 i +-1.0606061e+00 2.1638168e-01 i +-7.5757576e-01 2.5577912e-01 i +-4.5454545e-01 2.8369347e-01 i +-1.5151515e-01 2.9816622e-01 i +1.5151515e-01 2.9816622e-01 i +4.5454545e-01 2.8369347e-01 i +7.5757576e-01 2.5577912e-01 i +1.0606061e+00 2.1638168e-01 i +1.3636364e+00 1.6819310e-01 i +1.6666667e+00 1.1437994e-01 i +1.9696970e+00 5.8291956e-02 i +2.2727273e+00 3.1731498e-03 i +2.5757576e+00 -4.8092850e-02 i +2.8787879e+00 -9.3178121e-02 i +3.1818182e+00 -1.3043157e-01 i +3.4848485e+00 -1.5892178e-01 i +3.7878788e+00 -1.7840774e-01 i +4.0909091e+00 -1.8925117e-01 i +4.3939394e+00 -1.9228931e-01 i +4.6969697e+00 -1.8868807e-01 i +5.0000000e+00 -1.7979430e-01 i +5.3030303e+00 -1.6700223e-01 i +5.6060606e+00 -1.5164422e-01 i +5.9090909e+00 -1.3491113e-01 i +6.2121212e+00 -1.1780296e-01 i +6.5151515e+00 -1.0110702e-01 i +6.8181818e+00 -8.5398571e-02 i +7.1212121e+00 -7.1057888e-02 i +7.4242424e+00 -5.8297668e-02 i +7.7272727e+00 -4.7195413e-02 i +8.0303030e+00 -3.7726479e-02 i +8.3333333e+00 -2.9794790e-02 i +8.6363636e+00 -2.3259361e-02 i +8.9393939e+00 -1.7955780e-02 i +9.2424242e+00 -1.3712560e-02 i +9.5454545e+00 -1.0362753e-02 i +9.8484848e+00 -7.7515264e-03 i +1.0151515e+01 -5.7404907e-03 i +1.0454545e+01 -4.2095735e-03 i +1.0757576e+01 -3.0571566e-03 i +1.1060606e+01 -2.1990684e-03 i +1.1363636e+01 -1.5669021e-03 i +1.1666667e+01 -1.1060098e-03 i +1.1969697e+01 -7.7341929e-04 i +1.2272727e+01 -5.3583245e-04 i +1.2575758e+01 -3.6780325e-04 i +1.2878788e+01 -2.5014140e-04 i +1.3181818e+01 -1.6855715e-04 i +1.3484848e+01 -1.1253984e-04 i +1.3787879e+01 -7.4450441e-05 i +1.4090909e+01 -4.8801505e-05 i +1.4393939e+01 -3.1696136e-05 i +1.4696970e+01 -2.0398026e-05 i +1.5000000e+01 -1.3007078e-05 i + diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp.gnuplot b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp.gnuplot new file mode 100644 index 00000000000..709bdf2166a --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp.gnuplot @@ -0,0 +1,2 @@ +set table "gnuplot/pgfplots_exp.table"; set format "%.5f" +set format "%.7e";; set samples 25; set logscale y 2.71828182845905; plot [x=0:10] exp(x); diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp.table b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp.table new file mode 100644 index 00000000000..05ffaa9cf4a --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_exp.table @@ -0,0 +1,29 @@ + +#Curve 0 of 1, 25 points +#x y type +0.0000000e+00 0.0000000e+00 i +4.1666667e-01 4.1666667e-01 i +8.3333333e-01 8.3333333e-01 i +1.2500000e+00 1.2500000e+00 i +1.6666667e+00 1.6666667e+00 i +2.0833333e+00 2.0833333e+00 i +2.5000000e+00 2.5000000e+00 i +2.9166667e+00 2.9166667e+00 i +3.3333333e+00 3.3333333e+00 i +3.7500000e+00 3.7500000e+00 i +4.1666667e+00 4.1666667e+00 i +4.5833333e+00 4.5833333e+00 i +5.0000000e+00 5.0000000e+00 i +5.4166667e+00 5.4166667e+00 i +5.8333333e+00 5.8333333e+00 i +6.2500000e+00 6.2500000e+00 i +6.6666667e+00 6.6666667e+00 i +7.0833333e+00 7.0833333e+00 i +7.5000000e+00 7.5000000e+00 i +7.9166667e+00 7.9166667e+00 i +8.3333333e+00 8.3333333e+00 i +8.7500000e+00 8.7500000e+00 i +9.1666667e+00 9.1666667e+00 i +9.5833333e+00 9.5833333e+00 i +1.0000000e+01 1.0000000e+01 i + diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_filesuffix.gnuplot b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_filesuffix.gnuplot new file mode 100644 index 00000000000..3bbc4c5a6ec --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_filesuffix.gnuplot @@ -0,0 +1,2 @@ +set table "gnuplot/pgfplots_filesuffix.table"; set format "%.5f" +set format "%.7e";; set samples 25; plot [x=-5:5] (-x**5 - 242); diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_filesuffix.table b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_filesuffix.table new file mode 100644 index 00000000000..13b7b7a4299 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_filesuffix.table @@ -0,0 +1,29 @@ + +#Curve 0 of 1, 25 points +#x y type +-5.0000000e+00 2.8830000e+03 i +-4.5833333e+00 1.7805870e+03 i +-4.1666667e+00 1.0138674e+03 i +-3.7500000e+00 4.9957715e+02 i +-3.3333333e+00 1.6952263e+02 i +-2.9166667e+00 -3.0926364e+01 i +-2.5000000e+00 -1.4434375e+02 i +-2.0833333e+00 -2.0275414e+02 i +-1.6666667e+00 -2.2913992e+02 i +-1.2500000e+00 -2.3894824e+02 i +-8.3333333e-01 -2.4159812e+02 i +-4.1666667e-01 -2.4198744e+02 i +0.0000000e+00 -2.4200000e+02 i +4.1666667e-01 -2.4201256e+02 i +8.3333333e-01 -2.4240188e+02 i +1.2500000e+00 -2.4505176e+02 i +1.6666667e+00 -2.5486008e+02 i +2.0833333e+00 -2.8124586e+02 i +2.5000000e+00 -3.3965625e+02 i +2.9166667e+00 -4.5307364e+02 i +3.3333333e+00 -6.5352263e+02 i +3.7500000e+00 -9.8357715e+02 i +4.1666667e+00 -1.4978674e+03 i +4.5833333e+00 -2.2645870e+03 i +5.0000000e+00 -3.3670000e+03 i + diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_gnuplot_ppp.gnuplot b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_gnuplot_ppp.gnuplot new file mode 100644 index 00000000000..bee9ff15ac7 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_gnuplot_ppp.gnuplot @@ -0,0 +1,2 @@ +set table "gnuplot/pgfplots_gnuplot_ppp.table"; set format "%.5f" +set format "%.7e";; set samples 120; plot [x=-40:40] 10000*sin(x/3); diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_gnuplot_ppp.table b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_gnuplot_ppp.table new file mode 100644 index 00000000000..fa803afffdc --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_gnuplot_ppp.table @@ -0,0 +1,124 @@ + +#Curve 0 of 1, 120 points +#x y type +-4.0000000e+01 -6.9395153e+03 i +-3.9327731e+01 -5.1659813e+03 i +-3.8655462e+01 -3.1341153e+03 i +-3.7983193e+01 -9.4552356e+02 i +-3.7310924e+01 1.2903504e+03 i +-3.6638655e+01 3.4616986e+03 i +-3.5966387e+01 5.4599399e+03 i +-3.5294118e+01 7.1851493e+03 i +-3.4621849e+01 8.5510554e+03 i +-3.3949580e+01 9.4893542e+03 i +-3.3277311e+01 9.9531248e+03 i +-3.2605042e+01 9.9191756e+03 i +-3.1932773e+01 9.3892044e+03 i +-3.1260504e+01 8.3897132e+03 i +-3.0588235e+01 6.9706827e+03 i +-2.9915966e+01 5.2030737e+03 i +-2.9243697e+01 3.1752778e+03 i +-2.8571429e+01 9.8869771e+02 i +-2.7899160e+01 -1.2473235e+03 i +-2.7226891e+01 -3.4209706e+03 i +-2.6554622e+01 -5.4235474e+03 i +-2.5882353e+01 -7.1549122e+03 i +-2.5210084e+01 -8.5284858e+03 i +-2.4537815e+01 -9.4755806e+03 i +-2.3865546e+01 -9.9488360e+03 i +-2.3193277e+01 -9.9245862e+03 i +-2.2521008e+01 -9.4040438e+03 i +-2.1848739e+01 -8.4132391e+03 i +-2.1176471e+01 -7.0017189e+03 i +-2.0504202e+01 -5.2400681e+03 i +-1.9831933e+01 -3.2163804e+03 i +-1.9159664e+01 -1.0318533e+03 i +-1.8487395e+01 1.2042732e+03 i +-1.7815126e+01 3.3801783e+03 i +-1.7142857e+01 5.3870529e+03 i +-1.6470588e+01 7.1245405e+03 i +-1.5798319e+01 8.5057557e+03 i +-1.5126050e+01 9.4616288e+03 i +-1.4453782e+01 9.9443601e+03 i +-1.3781513e+01 9.9298100e+03 i +-1.3109244e+01 9.4187061e+03 i +-1.2436975e+01 8.4366068e+03 i +-1.1764706e+01 7.0326234e+03 i +-1.1092437e+01 5.2769639e+03 i +-1.0420168e+01 3.2574226e+03 i +-9.7478992e+00 1.0749894e+03 i +-9.0756303e+00 -1.1612002e+03 i +-8.4033613e+00 -3.3393223e+03 i +-7.7310924e+00 -5.3504570e+03 i +-7.0588235e+00 -7.0940348e+03 i +-6.3865546e+00 -8.4828655e+03 i +-5.7142857e+00 -9.4474989e+03 i +-5.0420168e+00 -9.9396971e+03 i +-4.3697479e+00 -9.9348470e+03 i +-3.6974790e+00 -9.4331913e+03 i +-3.0252101e+00 -8.4598158e+03 i +-2.3529412e+00 -7.0633955e+03 i +-1.6806723e+00 -5.3137605e+03 i +-1.0084034e+00 -3.2984035e+03 i +-3.3613445e-01 -1.1181053e+03 i +3.3613445e-01 1.1181053e+03 i +1.0084034e+00 3.2984035e+03 i +1.6806723e+00 5.3137605e+03 i +2.3529412e+00 7.0633955e+03 i +3.0252101e+00 8.4598158e+03 i +3.6974790e+00 9.4331913e+03 i +4.3697479e+00 9.9348470e+03 i +5.0420168e+00 9.9396971e+03 i +5.7142857e+00 9.4474989e+03 i +6.3865546e+00 8.4828655e+03 i +7.0588235e+00 7.0940348e+03 i +7.7310924e+00 5.3504570e+03 i +8.4033613e+00 3.3393223e+03 i +9.0756303e+00 1.1612002e+03 i +9.7478992e+00 -1.0749894e+03 i +1.0420168e+01 -3.2574226e+03 i +1.1092437e+01 -5.2769639e+03 i +1.1764706e+01 -7.0326234e+03 i +1.2436975e+01 -8.4366068e+03 i +1.3109244e+01 -9.4187061e+03 i +1.3781513e+01 -9.9298100e+03 i +1.4453782e+01 -9.9443601e+03 i +1.5126050e+01 -9.4616288e+03 i +1.5798319e+01 -8.5057557e+03 i +1.6470588e+01 -7.1245405e+03 i +1.7142857e+01 -5.3870529e+03 i +1.7815126e+01 -3.3801783e+03 i +1.8487395e+01 -1.2042732e+03 i +1.9159664e+01 1.0318533e+03 i +1.9831933e+01 3.2163804e+03 i +2.0504202e+01 5.2400681e+03 i +2.1176471e+01 7.0017189e+03 i +2.1848739e+01 8.4132391e+03 i +2.2521008e+01 9.4040438e+03 i +2.3193277e+01 9.9245862e+03 i +2.3865546e+01 9.9488360e+03 i +2.4537815e+01 9.4755806e+03 i +2.5210084e+01 8.5284858e+03 i +2.5882353e+01 7.1549122e+03 i +2.6554622e+01 5.4235474e+03 i +2.7226891e+01 3.4209706e+03 i +2.7899160e+01 1.2473235e+03 i +2.8571429e+01 -9.8869771e+02 i +2.9243697e+01 -3.1752778e+03 i +2.9915966e+01 -5.2030737e+03 i +3.0588235e+01 -6.9706827e+03 i +3.1260504e+01 -8.3897132e+03 i +3.1932773e+01 -9.3892044e+03 i +3.2605042e+01 -9.9191756e+03 i +3.3277311e+01 -9.9531248e+03 i +3.3949580e+01 -9.4893542e+03 i +3.4621849e+01 -8.5510554e+03 i +3.5294118e+01 -7.1851493e+03 i +3.5966387e+01 -5.4599399e+03 i +3.6638655e+01 -3.4616986e+03 i +3.7310924e+01 -1.2903504e+03 i +3.7983193e+01 9.4552356e+02 i +3.8655462e+01 3.1341153e+03 i +3.9327731e+01 5.1659813e+03 i +4.0000000e+01 6.9395153e+03 i + diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_parable.gnuplot b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_parable.gnuplot new file mode 100644 index 00000000000..9144ac39184 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_parable.gnuplot @@ -0,0 +1,2 @@ +set table "gnuplot/pgfplots_parable.table"; set format "%.5f" +set format "%.7e";; set samples 25; plot [x=-5:5] 4*x**2 - 5; diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_parable.table b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_parable.table new file mode 100644 index 00000000000..e014e557a37 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_parable.table @@ -0,0 +1,29 @@ + +#Curve 0 of 1, 25 points +#x y type +-5.0000000e+00 9.5000000e+01 i +-4.5833333e+00 7.9027778e+01 i +-4.1666667e+00 6.4444444e+01 i +-3.7500000e+00 5.1250000e+01 i +-3.3333333e+00 3.9444444e+01 i +-2.9166667e+00 2.9027778e+01 i +-2.5000000e+00 2.0000000e+01 i +-2.0833333e+00 1.2361111e+01 i +-1.6666667e+00 6.1111111e+00 i +-1.2500000e+00 1.2500000e+00 i +-8.3333333e-01 -2.2222222e+00 i +-4.1666667e-01 -4.3055556e+00 i +0.0000000e+00 -5.0000000e+00 i +4.1666667e-01 -4.3055556e+00 i +8.3333333e-01 -2.2222222e+00 i +1.2500000e+00 1.2500000e+00 i +1.6666667e+00 6.1111111e+00 i +2.0833333e+00 1.2361111e+01 i +2.5000000e+00 2.0000000e+01 i +2.9166667e+00 2.9027778e+01 i +3.3333333e+00 3.9444444e+01 i +3.7500000e+00 5.1250000e+01 i +4.1666667e+00 6.4444444e+01 i +4.5833333e+00 7.9027778e+01 i +5.0000000e+00 9.5000000e+01 i + diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_pow2.gnuplot b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_pow2.gnuplot new file mode 100644 index 00000000000..fd5e0ab7b3c --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_pow2.gnuplot @@ -0,0 +1,2 @@ +set table "gnuplot/pgfplots_pow2.table"; set format "%.5f" +set format "%.7e";; set samples 8; set logscale y 2.71828182845905; plot [x=0:10] 2**(-1.5*x -3); diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_pow2.table b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_pow2.table new file mode 100644 index 00000000000..e9ebe377a99 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_pow2.table @@ -0,0 +1,12 @@ + +#Curve 0 of 1, 8 points +#x y type +0.0000000e+00 -2.0794415e+00 i +1.4285714e+00 -3.5647569e+00 i +2.8571429e+00 -5.0500723e+00 i +4.2857143e+00 -6.5353877e+00 i +5.7142857e+00 -8.0207031e+00 i +7.1428571e+00 -9.5060185e+00 i +8.5714286e+00 -1.0991334e+01 i +1.0000000e+01 -1.2476649e+01 i + diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_sin.gnuplot b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_sin.gnuplot new file mode 100644 index 00000000000..2bc6c2ecd64 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_sin.gnuplot @@ -0,0 +1,2 @@ +set table "gnuplot/pgfplots_sin.table"; set format "%.5f" +set format "%.7e";; set samples 25; plot [x=-5:5] sin(x); diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_sin.table b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_sin.table new file mode 100644 index 00000000000..ed5cd95f8f6 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_sin.table @@ -0,0 +1,29 @@ + +#Curve 0 of 1, 25 points +#x y type +-5.0000000e+00 9.5892427e-01 i +-4.5833333e+00 9.9168387e-01 i +-4.1666667e+00 8.5475261e-01 i +-3.7500000e+00 5.7156132e-01 i +-3.3333333e+00 1.9056796e-01 i +-2.9166667e+00 -2.2303421e-01 i +-2.5000000e+00 -5.9847214e-01 i +-2.0833333e+00 -8.7150319e-01 i +-1.6666667e+00 -9.9540796e-01 i +-1.2500000e+00 -9.4898462e-01 i +-8.3333333e-01 -7.4017685e-01 i +-4.1666667e-01 -4.0471456e-01 i +0.0000000e+00 0.0000000e+00 i +4.1666667e-01 4.0471456e-01 i +8.3333333e-01 7.4017685e-01 i +1.2500000e+00 9.4898462e-01 i +1.6666667e+00 9.9540796e-01 i +2.0833333e+00 8.7150319e-01 i +2.5000000e+00 5.9847214e-01 i +2.9166667e+00 2.2303421e-01 i +3.3333333e+00 -1.9056796e-01 i +3.7500000e+00 -5.7156132e-01 i +4.1666667e+00 -8.5475261e-01 i +4.5833333e+00 -9.9168387e-01 i +5.0000000e+00 -9.5892427e-01 i + diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_tangens.gnuplot b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_tangens.gnuplot new file mode 100644 index 00000000000..483ee2b9a13 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_tangens.gnuplot @@ -0,0 +1,2 @@ +set table "gnuplot/pgfplots_tangens.table"; set format "%.5f" +set format "%.7e";; set samples 1000; plot [x=-1.5*pi:1.5*pi] tan(x); diff --git a/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_tangens.table b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_tangens.table new file mode 100644 index 00000000000..41050d8adee --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/gnuplot/pgfplots_tangens.table @@ -0,0 +1,1004 @@ + +#Curve 0 of 1, 1000 points +#x y type +-4.7123890e+00 -5.4437465e+15 i +-4.7029548e+00 -1.0599405e+02 i +-4.6935206e+00 -5.2992306e+01 i +-4.6840863e+00 -3.5322963e+01 i +-4.6746521e+00 -2.6486718e+01 i +-4.6652179e+00 -2.1183712e+01 i +-4.6557837e+00 -1.7647326e+01 i +-4.6463495e+00 -1.5120436e+01 i +-4.6369153e+00 -1.3224482e+01 i +-4.6274811e+00 -1.1749150e+01 i +-4.6180469e+00 -1.0568253e+01 i +-4.6086126e+00 -9.6014914e+00 i +-4.5991784e+00 -8.7953302e+00 i +-4.5897442e+00 -8.1127075e+00 i +-4.5803100e+00 -7.5271504e+00 i +-4.5708758e+00 -7.0192453e+00 i +-4.5614416e+00 -6.5744321e+00 i +-4.5520074e+00 -6.1815765e+00 i +-4.5425732e+00 -5.8320185e+00 i +-4.5331389e+00 -5.5189212e+00 i +-4.5237047e+00 -5.2368151e+00 i +-4.5142705e+00 -4.9812724e+00 i +-4.5048363e+00 -4.7486705e+00 i +-4.4954021e+00 -4.5360166e+00 i +-4.4859679e+00 -4.3408168e+00 i +-4.4765337e+00 -4.1609761e+00 i +-4.4670995e+00 -3.9947221e+00 i +-4.4576653e+00 -3.8405445e+00 i +-4.4482310e+00 -3.6971490e+00 i +-4.4387968e+00 -3.5634198e+00 i +-4.4293626e+00 -3.4383899e+00 i +-4.4199284e+00 -3.3212169e+00 i +-4.4104942e+00 -3.2111639e+00 i +-4.4010600e+00 -3.1075830e+00 i +-4.3916258e+00 -3.0099027e+00 i +-4.3821916e+00 -2.9176170e+00 i +-4.3727573e+00 -2.8302756e+00 i +-4.3633231e+00 -2.7474774e+00 i +-4.3538889e+00 -2.6688632e+00 i +-4.3444547e+00 -2.5941106e+00 i +-4.3350205e+00 -2.5229297e+00 i +-4.3255863e+00 -2.4550585e+00 i +-4.3161521e+00 -2.3902602e+00 i +-4.3067179e+00 -2.3283201e+00 i +-4.2972836e+00 -2.2690426e+00 i +-4.2878494e+00 -2.2122499e+00 i +-4.2784152e+00 -2.1577794e+00 i +-4.2689810e+00 -2.1054824e+00 i +-4.2595468e+00 -2.0552227e+00 i +-4.2501126e+00 -2.0068749e+00 i +-4.2406784e+00 -1.9603240e+00 i +-4.2312442e+00 -1.9154636e+00 i +-4.2218099e+00 -1.8721959e+00 i +-4.2123757e+00 -1.8304301e+00 i +-4.2029415e+00 -1.7900824e+00 i +-4.1935073e+00 -1.7510748e+00 i +-4.1840731e+00 -1.7133352e+00 i +-4.1746389e+00 -1.6767962e+00 i +-4.1652047e+00 -1.6413953e+00 i +-4.1557705e+00 -1.6070741e+00 i +-4.1463363e+00 -1.5737781e+00 i +-4.1369020e+00 -1.5414563e+00 i +-4.1274678e+00 -1.5100612e+00 i +-4.1180336e+00 -1.4795481e+00 i +-4.1085994e+00 -1.4498751e+00 i +-4.0991652e+00 -1.4210030e+00 i +-4.0897310e+00 -1.3928947e+00 i +-4.0802968e+00 -1.3655157e+00 i +-4.0708626e+00 -1.3388330e+00 i +-4.0614283e+00 -1.3128161e+00 i +-4.0519941e+00 -1.2874357e+00 i +-4.0425599e+00 -1.2626645e+00 i +-4.0331257e+00 -1.2384766e+00 i +-4.0236915e+00 -1.2148473e+00 i +-4.0142573e+00 -1.1917536e+00 i +-4.0048231e+00 -1.1691734e+00 i +-3.9953889e+00 -1.1470859e+00 i +-3.9859546e+00 -1.1254714e+00 i +-3.9765204e+00 -1.1043110e+00 i +-3.9670862e+00 -1.0835871e+00 i +-3.9576520e+00 -1.0632825e+00 i +-3.9482178e+00 -1.0433813e+00 i +-3.9387836e+00 -1.0238681e+00 i +-3.9293494e+00 -1.0047283e+00 i +-3.9199152e+00 -9.8594788e-01 i +-3.9104809e+00 -9.6751365e-01 i +-3.9010467e+00 -9.4941292e-01 i +-3.8916125e+00 -9.3163357e-01 i +-3.8821783e+00 -9.1416404e-01 i +-3.8727441e+00 -8.9699328e-01 i +-3.8633099e+00 -8.8011069e-01 i +-3.8538757e+00 -8.6350617e-01 i +-3.8444415e+00 -8.4717000e-01 i +-3.8350072e+00 -8.3109290e-01 i +-3.8255730e+00 -8.1526596e-01 i +-3.8161388e+00 -7.9968062e-01 i +-3.8067046e+00 -7.8432870e-01 i +-3.7972704e+00 -7.6920231e-01 i +-3.7878362e+00 -7.5429388e-01 i +-3.7784020e+00 -7.3959614e-01 i +-3.7689678e+00 -7.2510210e-01 i +-3.7595336e+00 -7.1080501e-01 i +-3.7500993e+00 -6.9669840e-01 i +-3.7406651e+00 -6.8277602e-01 i +-3.7312309e+00 -6.6903186e-01 i +-3.7217967e+00 -6.5546012e-01 i +-3.7123625e+00 -6.4205520e-01 i +-3.7029283e+00 -6.2881171e-01 i +-3.6934941e+00 -6.1572442e-01 i +-3.6840599e+00 -6.0278830e-01 i +-3.6746256e+00 -5.8999849e-01 i +-3.6651914e+00 -5.7735027e-01 i +-3.6557572e+00 -5.6483909e-01 i +-3.6463230e+00 -5.5246056e-01 i +-3.6368888e+00 -5.4021039e-01 i +-3.6274546e+00 -5.2808446e-01 i +-3.6180204e+00 -5.1607875e-01 i +-3.6085862e+00 -5.0418939e-01 i +-3.5991519e+00 -4.9241261e-01 i +-3.5897177e+00 -4.8074474e-01 i +-3.5802835e+00 -4.6918223e-01 i +-3.5708493e+00 -4.5772163e-01 i +-3.5614151e+00 -4.4635959e-01 i +-3.5519809e+00 -4.3509285e-01 i +-3.5425467e+00 -4.2391822e-01 i +-3.5331125e+00 -4.1283263e-01 i +-3.5236782e+00 -4.0183305e-01 i +-3.5142440e+00 -3.9091656e-01 i +-3.5048098e+00 -3.8008029e-01 i +-3.4953756e+00 -3.6932146e-01 i +-3.4859414e+00 -3.5863735e-01 i +-3.4765072e+00 -3.4802529e-01 i +-3.4670730e+00 -3.3748270e-01 i +-3.4576388e+00 -3.2700702e-01 i +-3.4482045e+00 -3.1659578e-01 i +-3.4387703e+00 -3.0624656e-01 i +-3.4293361e+00 -2.9595696e-01 i +-3.4199019e+00 -2.8572467e-01 i +-3.4104677e+00 -2.7554739e-01 i +-3.4010335e+00 -2.6542289e-01 i +-3.3915993e+00 -2.5534898e-01 i +-3.3821651e+00 -2.4532348e-01 i +-3.3727309e+00 -2.3534428e-01 i +-3.3632966e+00 -2.2540930e-01 i +-3.3538624e+00 -2.1551649e-01 i +-3.3444282e+00 -2.0566382e-01 i +-3.3349940e+00 -1.9584931e-01 i +-3.3255598e+00 -1.8607101e-01 i +-3.3161256e+00 -1.7632698e-01 i +-3.3066914e+00 -1.6661531e-01 i +-3.2972572e+00 -1.5693413e-01 i +-3.2878229e+00 -1.4728158e-01 i +-3.2783887e+00 -1.3765581e-01 i +-3.2689545e+00 -1.2805501e-01 i +-3.2595203e+00 -1.1847738e-01 i +-3.2500861e+00 -1.0892114e-01 i +-3.2406519e+00 -9.9384519e-02 i +-3.2312177e+00 -8.9865764e-02 i +-3.2217835e+00 -8.0363137e-02 i +-3.2123492e+00 -7.0874909e-02 i +-3.2029150e+00 -6.1399361e-02 i +-3.1934808e+00 -5.1934785e-02 i +-3.1840466e+00 -4.2479479e-02 i +-3.1746124e+00 -3.3031748e-02 i +-3.1651782e+00 -2.3589905e-02 i +-3.1557440e+00 -1.4152263e-02 i +-3.1463098e+00 -4.7171411e-03 i +-3.1368755e+00 4.7171411e-03 i +-3.1274413e+00 1.4152263e-02 i +-3.1180071e+00 2.3589905e-02 i +-3.1085729e+00 3.3031748e-02 i +-3.0991387e+00 4.2479479e-02 i +-3.0897045e+00 5.1934785e-02 i +-3.0802703e+00 6.1399361e-02 i +-3.0708361e+00 7.0874909e-02 i +-3.0614019e+00 8.0363137e-02 i +-3.0519676e+00 8.9865764e-02 i +-3.0425334e+00 9.9384519e-02 i +-3.0330992e+00 1.0892114e-01 i +-3.0236650e+00 1.1847738e-01 i +-3.0142308e+00 1.2805501e-01 i +-3.0047966e+00 1.3765581e-01 i +-2.9953624e+00 1.4728158e-01 i +-2.9859282e+00 1.5693413e-01 i +-2.9764939e+00 1.6661531e-01 i +-2.9670597e+00 1.7632698e-01 i +-2.9576255e+00 1.8607101e-01 i +-2.9481913e+00 1.9584931e-01 i +-2.9387571e+00 2.0566382e-01 i +-2.9293229e+00 2.1551649e-01 i +-2.9198887e+00 2.2540930e-01 i +-2.9104545e+00 2.3534428e-01 i +-2.9010202e+00 2.4532348e-01 i +-2.8915860e+00 2.5534898e-01 i +-2.8821518e+00 2.6542289e-01 i +-2.8727176e+00 2.7554739e-01 i +-2.8632834e+00 2.8572467e-01 i +-2.8538492e+00 2.9595696e-01 i +-2.8444150e+00 3.0624656e-01 i +-2.8349808e+00 3.1659578e-01 i +-2.8255465e+00 3.2700702e-01 i +-2.8161123e+00 3.3748270e-01 i +-2.8066781e+00 3.4802529e-01 i +-2.7972439e+00 3.5863735e-01 i +-2.7878097e+00 3.6932146e-01 i +-2.7783755e+00 3.8008029e-01 i +-2.7689413e+00 3.9091656e-01 i +-2.7595071e+00 4.0183305e-01 i +-2.7500728e+00 4.1283263e-01 i +-2.7406386e+00 4.2391822e-01 i +-2.7312044e+00 4.3509285e-01 i +-2.7217702e+00 4.4635959e-01 i +-2.7123360e+00 4.5772163e-01 i +-2.7029018e+00 4.6918223e-01 i +-2.6934676e+00 4.8074474e-01 i +-2.6840334e+00 4.9241261e-01 i +-2.6745992e+00 5.0418939e-01 i +-2.6651649e+00 5.1607875e-01 i +-2.6557307e+00 5.2808446e-01 i +-2.6462965e+00 5.4021039e-01 i +-2.6368623e+00 5.5246056e-01 i +-2.6274281e+00 5.6483909e-01 i +-2.6179939e+00 5.7735027e-01 i +-2.6085597e+00 5.8999849e-01 i +-2.5991255e+00 6.0278830e-01 i +-2.5896912e+00 6.1572442e-01 i +-2.5802570e+00 6.2881171e-01 i +-2.5708228e+00 6.4205520e-01 i +-2.5613886e+00 6.5546012e-01 i +-2.5519544e+00 6.6903186e-01 i +-2.5425202e+00 6.8277602e-01 i +-2.5330860e+00 6.9669840e-01 i +-2.5236518e+00 7.1080501e-01 i +-2.5142175e+00 7.2510210e-01 i +-2.5047833e+00 7.3959614e-01 i +-2.4953491e+00 7.5429388e-01 i +-2.4859149e+00 7.6920231e-01 i +-2.4764807e+00 7.8432870e-01 i +-2.4670465e+00 7.9968062e-01 i +-2.4576123e+00 8.1526596e-01 i +-2.4481781e+00 8.3109290e-01 i +-2.4387438e+00 8.4717000e-01 i +-2.4293096e+00 8.6350617e-01 i +-2.4198754e+00 8.8011069e-01 i +-2.4104412e+00 8.9699328e-01 i +-2.4010070e+00 9.1416404e-01 i +-2.3915728e+00 9.3163357e-01 i +-2.3821386e+00 9.4941292e-01 i +-2.3727044e+00 9.6751365e-01 i +-2.3632701e+00 9.8594788e-01 i +-2.3538359e+00 1.0047283e+00 i +-2.3444017e+00 1.0238681e+00 i +-2.3349675e+00 1.0433813e+00 i +-2.3255333e+00 1.0632825e+00 i +-2.3160991e+00 1.0835871e+00 i +-2.3066649e+00 1.1043110e+00 i +-2.2972307e+00 1.1254714e+00 i +-2.2877965e+00 1.1470859e+00 i +-2.2783622e+00 1.1691734e+00 i +-2.2689280e+00 1.1917536e+00 i +-2.2594938e+00 1.2148473e+00 i +-2.2500596e+00 1.2384766e+00 i +-2.2406254e+00 1.2626645e+00 i +-2.2311912e+00 1.2874357e+00 i +-2.2217570e+00 1.3128161e+00 i +-2.2123228e+00 1.3388330e+00 i +-2.2028885e+00 1.3655157e+00 i +-2.1934543e+00 1.3928947e+00 i +-2.1840201e+00 1.4210030e+00 i +-2.1745859e+00 1.4498751e+00 i +-2.1651517e+00 1.4795481e+00 i +-2.1557175e+00 1.5100612e+00 i +-2.1462833e+00 1.5414563e+00 i +-2.1368491e+00 1.5737781e+00 i +-2.1274148e+00 1.6070741e+00 i +-2.1179806e+00 1.6413953e+00 i +-2.1085464e+00 1.6767962e+00 i +-2.0991122e+00 1.7133352e+00 i +-2.0896780e+00 1.7510748e+00 i +-2.0802438e+00 1.7900824e+00 i +-2.0708096e+00 1.8304301e+00 i +-2.0613754e+00 1.8721959e+00 i +-2.0519411e+00 1.9154636e+00 i +-2.0425069e+00 1.9603240e+00 i +-2.0330727e+00 2.0068749e+00 i +-2.0236385e+00 2.0552227e+00 i +-2.0142043e+00 2.1054824e+00 i +-2.0047701e+00 2.1577794e+00 i +-1.9953359e+00 2.2122499e+00 i +-1.9859017e+00 2.2690426e+00 i +-1.9764675e+00 2.3283201e+00 i +-1.9670332e+00 2.3902602e+00 i +-1.9575990e+00 2.4550585e+00 i +-1.9481648e+00 2.5229297e+00 i +-1.9387306e+00 2.5941106e+00 i +-1.9292964e+00 2.6688632e+00 i +-1.9198622e+00 2.7474774e+00 i +-1.9104280e+00 2.8302756e+00 i +-1.9009938e+00 2.9176170e+00 i +-1.8915595e+00 3.0099027e+00 i +-1.8821253e+00 3.1075830e+00 i +-1.8726911e+00 3.2111639e+00 i +-1.8632569e+00 3.3212169e+00 i +-1.8538227e+00 3.4383899e+00 i +-1.8443885e+00 3.5634198e+00 i +-1.8349543e+00 3.6971490e+00 i +-1.8255201e+00 3.8405445e+00 i +-1.8160858e+00 3.9947221e+00 i +-1.8066516e+00 4.1609761e+00 i +-1.7972174e+00 4.3408168e+00 i +-1.7877832e+00 4.5360166e+00 i +-1.7783490e+00 4.7486705e+00 i +-1.7689148e+00 4.9812724e+00 i +-1.7594806e+00 5.2368151e+00 i +-1.7500464e+00 5.5189212e+00 i +-1.7406121e+00 5.8320185e+00 i +-1.7311779e+00 6.1815765e+00 i +-1.7217437e+00 6.5744321e+00 i +-1.7123095e+00 7.0192453e+00 i +-1.7028753e+00 7.5271504e+00 i +-1.6934411e+00 8.1127075e+00 i +-1.6840069e+00 8.7953302e+00 i +-1.6745727e+00 9.6014914e+00 i +-1.6651384e+00 1.0568253e+01 i +-1.6557042e+00 1.1749150e+01 i +-1.6462700e+00 1.3224482e+01 i +-1.6368358e+00 1.5120436e+01 i +-1.6274016e+00 1.7647326e+01 i +-1.6179674e+00 2.1183712e+01 i +-1.6085332e+00 2.6486718e+01 i +-1.5990990e+00 3.5322963e+01 i +-1.5896648e+00 5.2992306e+01 i +-1.5802305e+00 1.0599405e+02 i +-1.5707963e+00 -1.6331239e+16 i +-1.5613621e+00 -1.0599405e+02 i +-1.5519279e+00 -5.2992306e+01 i +-1.5424937e+00 -3.5322963e+01 i +-1.5330595e+00 -2.6486718e+01 i +-1.5236253e+00 -2.1183712e+01 i +-1.5141911e+00 -1.7647326e+01 i +-1.5047568e+00 -1.5120436e+01 i +-1.4953226e+00 -1.3224482e+01 i +-1.4858884e+00 -1.1749150e+01 i +-1.4764542e+00 -1.0568253e+01 i +-1.4670200e+00 -9.6014914e+00 i +-1.4575858e+00 -8.7953302e+00 i +-1.4481516e+00 -8.1127075e+00 i +-1.4387174e+00 -7.5271504e+00 i +-1.4292831e+00 -7.0192453e+00 i +-1.4198489e+00 -6.5744321e+00 i +-1.4104147e+00 -6.1815765e+00 i +-1.4009805e+00 -5.8320185e+00 i +-1.3915463e+00 -5.5189212e+00 i +-1.3821121e+00 -5.2368151e+00 i +-1.3726779e+00 -4.9812724e+00 i +-1.3632437e+00 -4.7486705e+00 i +-1.3538094e+00 -4.5360166e+00 i +-1.3443752e+00 -4.3408168e+00 i +-1.3349410e+00 -4.1609761e+00 i +-1.3255068e+00 -3.9947221e+00 i +-1.3160726e+00 -3.8405445e+00 i +-1.3066384e+00 -3.6971490e+00 i +-1.2972042e+00 -3.5634198e+00 i +-1.2877700e+00 -3.4383899e+00 i +-1.2783357e+00 -3.3212169e+00 i +-1.2689015e+00 -3.2111639e+00 i +-1.2594673e+00 -3.1075830e+00 i +-1.2500331e+00 -3.0099027e+00 i +-1.2405989e+00 -2.9176170e+00 i +-1.2311647e+00 -2.8302756e+00 i +-1.2217305e+00 -2.7474774e+00 i +-1.2122963e+00 -2.6688632e+00 i +-1.2028621e+00 -2.5941106e+00 i +-1.1934278e+00 -2.5229297e+00 i +-1.1839936e+00 -2.4550585e+00 i +-1.1745594e+00 -2.3902602e+00 i +-1.1651252e+00 -2.3283201e+00 i +-1.1556910e+00 -2.2690426e+00 i +-1.1462568e+00 -2.2122499e+00 i +-1.1368226e+00 -2.1577794e+00 i +-1.1273884e+00 -2.1054824e+00 i +-1.1179541e+00 -2.0552227e+00 i +-1.1085199e+00 -2.0068749e+00 i +-1.0990857e+00 -1.9603240e+00 i +-1.0896515e+00 -1.9154636e+00 i +-1.0802173e+00 -1.8721959e+00 i +-1.0707831e+00 -1.8304301e+00 i +-1.0613489e+00 -1.7900824e+00 i +-1.0519147e+00 -1.7510748e+00 i +-1.0424804e+00 -1.7133352e+00 i +-1.0330462e+00 -1.6767962e+00 i +-1.0236120e+00 -1.6413953e+00 i +-1.0141778e+00 -1.6070741e+00 i +-1.0047436e+00 -1.5737781e+00 i +-9.9530938e-01 -1.5414563e+00 i +-9.8587517e-01 -1.5100612e+00 i +-9.7644096e-01 -1.4795481e+00 i +-9.6700675e-01 -1.4498751e+00 i +-9.5757254e-01 -1.4210030e+00 i +-9.4813832e-01 -1.3928947e+00 i +-9.3870411e-01 -1.3655157e+00 i +-9.2926990e-01 -1.3388330e+00 i +-9.1983569e-01 -1.3128161e+00 i +-9.1040147e-01 -1.2874357e+00 i +-9.0096726e-01 -1.2626645e+00 i +-8.9153305e-01 -1.2384766e+00 i +-8.8209884e-01 -1.2148473e+00 i +-8.7266463e-01 -1.1917536e+00 i +-8.6323041e-01 -1.1691734e+00 i +-8.5379620e-01 -1.1470859e+00 i +-8.4436199e-01 -1.1254714e+00 i +-8.3492778e-01 -1.1043110e+00 i +-8.2549357e-01 -1.0835871e+00 i +-8.1605935e-01 -1.0632825e+00 i +-8.0662514e-01 -1.0433813e+00 i +-7.9719093e-01 -1.0238681e+00 i +-7.8775672e-01 -1.0047283e+00 i +-7.7832250e-01 -9.8594788e-01 i +-7.6888829e-01 -9.6751365e-01 i +-7.5945408e-01 -9.4941292e-01 i +-7.5001987e-01 -9.3163357e-01 i +-7.4058566e-01 -9.1416404e-01 i +-7.3115144e-01 -8.9699328e-01 i +-7.2171723e-01 -8.8011069e-01 i +-7.1228302e-01 -8.6350617e-01 i +-7.0284881e-01 -8.4717000e-01 i +-6.9341459e-01 -8.3109290e-01 i +-6.8398038e-01 -8.1526596e-01 i +-6.7454617e-01 -7.9968062e-01 i +-6.6511196e-01 -7.8432870e-01 i +-6.5567775e-01 -7.6920231e-01 i +-6.4624353e-01 -7.5429388e-01 i +-6.3680932e-01 -7.3959614e-01 i +-6.2737511e-01 -7.2510210e-01 i +-6.1794090e-01 -7.1080501e-01 i +-6.0850669e-01 -6.9669840e-01 i +-5.9907247e-01 -6.8277602e-01 i +-5.8963826e-01 -6.6903186e-01 i +-5.8020405e-01 -6.5546012e-01 i +-5.7076984e-01 -6.4205520e-01 i +-5.6133562e-01 -6.2881171e-01 i +-5.5190141e-01 -6.1572442e-01 i +-5.4246720e-01 -6.0278830e-01 i +-5.3303299e-01 -5.8999849e-01 i +-5.2359878e-01 -5.7735027e-01 i +-5.1416456e-01 -5.6483909e-01 i +-5.0473035e-01 -5.5246056e-01 i +-4.9529614e-01 -5.4021039e-01 i +-4.8586193e-01 -5.2808446e-01 i +-4.7642771e-01 -5.1607875e-01 i +-4.6699350e-01 -5.0418939e-01 i +-4.5755929e-01 -4.9241261e-01 i +-4.4812508e-01 -4.8074474e-01 i +-4.3869087e-01 -4.6918223e-01 i +-4.2925665e-01 -4.5772163e-01 i +-4.1982244e-01 -4.4635959e-01 i +-4.1038823e-01 -4.3509285e-01 i +-4.0095402e-01 -4.2391822e-01 i +-3.9151981e-01 -4.1283263e-01 i +-3.8208559e-01 -4.0183305e-01 i +-3.7265138e-01 -3.9091656e-01 i +-3.6321717e-01 -3.8008029e-01 i +-3.5378296e-01 -3.6932146e-01 i +-3.4434874e-01 -3.5863735e-01 i +-3.3491453e-01 -3.4802529e-01 i +-3.2548032e-01 -3.3748270e-01 i +-3.1604611e-01 -3.2700702e-01 i +-3.0661190e-01 -3.1659578e-01 i +-2.9717768e-01 -3.0624656e-01 i +-2.8774347e-01 -2.9595696e-01 i +-2.7830926e-01 -2.8572467e-01 i +-2.6887505e-01 -2.7554739e-01 i +-2.5944083e-01 -2.6542289e-01 i +-2.5000662e-01 -2.5534898e-01 i +-2.4057241e-01 -2.4532348e-01 i +-2.3113820e-01 -2.3534428e-01 i +-2.2170399e-01 -2.2540930e-01 i +-2.1226977e-01 -2.1551649e-01 i +-2.0283556e-01 -2.0566382e-01 i +-1.9340135e-01 -1.9584931e-01 i +-1.8396714e-01 -1.8607101e-01 i +-1.7453293e-01 -1.7632698e-01 i +-1.6509871e-01 -1.6661531e-01 i +-1.5566450e-01 -1.5693413e-01 i +-1.4623029e-01 -1.4728158e-01 i +-1.3679608e-01 -1.3765581e-01 i +-1.2736186e-01 -1.2805501e-01 i +-1.1792765e-01 -1.1847738e-01 i +-1.0849344e-01 -1.0892114e-01 i +-9.9059228e-02 -9.9384519e-02 i +-8.9625016e-02 -8.9865764e-02 i +-8.0190803e-02 -8.0363137e-02 i +-7.0756591e-02 -7.0874909e-02 i +-6.1322379e-02 -6.1399361e-02 i +-5.1888167e-02 -5.1934785e-02 i +-4.2453955e-02 -4.2479479e-02 i +-3.3019743e-02 -3.3031748e-02 i +-2.3585530e-02 -2.3589905e-02 i +-1.4151318e-02 -1.4152263e-02 i +-4.7171061e-03 -4.7171411e-03 i +4.7171061e-03 4.7171411e-03 i +1.4151318e-02 1.4152263e-02 i +2.3585530e-02 2.3589905e-02 i +3.3019743e-02 3.3031748e-02 i +4.2453955e-02 4.2479479e-02 i +5.1888167e-02 5.1934785e-02 i +6.1322379e-02 6.1399361e-02 i +7.0756591e-02 7.0874909e-02 i +8.0190803e-02 8.0363137e-02 i +8.9625016e-02 8.9865764e-02 i +9.9059228e-02 9.9384519e-02 i +1.0849344e-01 1.0892114e-01 i +1.1792765e-01 1.1847738e-01 i +1.2736186e-01 1.2805501e-01 i +1.3679608e-01 1.3765581e-01 i +1.4623029e-01 1.4728158e-01 i +1.5566450e-01 1.5693413e-01 i +1.6509871e-01 1.6661531e-01 i +1.7453293e-01 1.7632698e-01 i +1.8396714e-01 1.8607101e-01 i +1.9340135e-01 1.9584931e-01 i +2.0283556e-01 2.0566382e-01 i +2.1226977e-01 2.1551649e-01 i +2.2170399e-01 2.2540930e-01 i +2.3113820e-01 2.3534428e-01 i +2.4057241e-01 2.4532348e-01 i +2.5000662e-01 2.5534898e-01 i +2.5944083e-01 2.6542289e-01 i +2.6887505e-01 2.7554739e-01 i +2.7830926e-01 2.8572467e-01 i +2.8774347e-01 2.9595696e-01 i +2.9717768e-01 3.0624656e-01 i +3.0661190e-01 3.1659578e-01 i +3.1604611e-01 3.2700702e-01 i +3.2548032e-01 3.3748270e-01 i +3.3491453e-01 3.4802529e-01 i +3.4434874e-01 3.5863735e-01 i +3.5378296e-01 3.6932146e-01 i +3.6321717e-01 3.8008029e-01 i +3.7265138e-01 3.9091656e-01 i +3.8208559e-01 4.0183305e-01 i +3.9151981e-01 4.1283263e-01 i +4.0095402e-01 4.2391822e-01 i +4.1038823e-01 4.3509285e-01 i +4.1982244e-01 4.4635959e-01 i +4.2925665e-01 4.5772163e-01 i +4.3869087e-01 4.6918223e-01 i +4.4812508e-01 4.8074474e-01 i +4.5755929e-01 4.9241261e-01 i +4.6699350e-01 5.0418939e-01 i +4.7642771e-01 5.1607875e-01 i +4.8586193e-01 5.2808446e-01 i +4.9529614e-01 5.4021039e-01 i +5.0473035e-01 5.5246056e-01 i +5.1416456e-01 5.6483909e-01 i +5.2359878e-01 5.7735027e-01 i +5.3303299e-01 5.8999849e-01 i +5.4246720e-01 6.0278830e-01 i +5.5190141e-01 6.1572442e-01 i +5.6133562e-01 6.2881171e-01 i +5.7076984e-01 6.4205520e-01 i +5.8020405e-01 6.5546012e-01 i +5.8963826e-01 6.6903186e-01 i +5.9907247e-01 6.8277602e-01 i +6.0850669e-01 6.9669840e-01 i +6.1794090e-01 7.1080501e-01 i +6.2737511e-01 7.2510210e-01 i +6.3680932e-01 7.3959614e-01 i +6.4624353e-01 7.5429388e-01 i +6.5567775e-01 7.6920231e-01 i +6.6511196e-01 7.8432870e-01 i +6.7454617e-01 7.9968062e-01 i +6.8398038e-01 8.1526596e-01 i +6.9341459e-01 8.3109290e-01 i +7.0284881e-01 8.4717000e-01 i +7.1228302e-01 8.6350617e-01 i +7.2171723e-01 8.8011069e-01 i +7.3115144e-01 8.9699328e-01 i +7.4058566e-01 9.1416404e-01 i +7.5001987e-01 9.3163357e-01 i +7.5945408e-01 9.4941292e-01 i +7.6888829e-01 9.6751365e-01 i +7.7832250e-01 9.8594788e-01 i +7.8775672e-01 1.0047283e+00 i +7.9719093e-01 1.0238681e+00 i +8.0662514e-01 1.0433813e+00 i +8.1605935e-01 1.0632825e+00 i +8.2549357e-01 1.0835871e+00 i +8.3492778e-01 1.1043110e+00 i +8.4436199e-01 1.1254714e+00 i +8.5379620e-01 1.1470859e+00 i +8.6323041e-01 1.1691734e+00 i +8.7266463e-01 1.1917536e+00 i +8.8209884e-01 1.2148473e+00 i +8.9153305e-01 1.2384766e+00 i +9.0096726e-01 1.2626645e+00 i +9.1040147e-01 1.2874357e+00 i +9.1983569e-01 1.3128161e+00 i +9.2926990e-01 1.3388330e+00 i +9.3870411e-01 1.3655157e+00 i +9.4813832e-01 1.3928947e+00 i +9.5757254e-01 1.4210030e+00 i +9.6700675e-01 1.4498751e+00 i +9.7644096e-01 1.4795481e+00 i +9.8587517e-01 1.5100612e+00 i +9.9530938e-01 1.5414563e+00 i +1.0047436e+00 1.5737781e+00 i +1.0141778e+00 1.6070741e+00 i +1.0236120e+00 1.6413953e+00 i +1.0330462e+00 1.6767962e+00 i +1.0424804e+00 1.7133352e+00 i +1.0519147e+00 1.7510748e+00 i +1.0613489e+00 1.7900824e+00 i +1.0707831e+00 1.8304301e+00 i +1.0802173e+00 1.8721959e+00 i +1.0896515e+00 1.9154636e+00 i +1.0990857e+00 1.9603240e+00 i +1.1085199e+00 2.0068749e+00 i +1.1179541e+00 2.0552227e+00 i +1.1273884e+00 2.1054824e+00 i +1.1368226e+00 2.1577794e+00 i +1.1462568e+00 2.2122499e+00 i +1.1556910e+00 2.2690426e+00 i +1.1651252e+00 2.3283201e+00 i +1.1745594e+00 2.3902602e+00 i +1.1839936e+00 2.4550585e+00 i +1.1934278e+00 2.5229297e+00 i +1.2028621e+00 2.5941106e+00 i +1.2122963e+00 2.6688632e+00 i +1.2217305e+00 2.7474774e+00 i +1.2311647e+00 2.8302756e+00 i +1.2405989e+00 2.9176170e+00 i +1.2500331e+00 3.0099027e+00 i +1.2594673e+00 3.1075830e+00 i +1.2689015e+00 3.2111639e+00 i +1.2783357e+00 3.3212169e+00 i +1.2877700e+00 3.4383899e+00 i +1.2972042e+00 3.5634198e+00 i +1.3066384e+00 3.6971490e+00 i +1.3160726e+00 3.8405445e+00 i +1.3255068e+00 3.9947221e+00 i +1.3349410e+00 4.1609761e+00 i +1.3443752e+00 4.3408168e+00 i +1.3538094e+00 4.5360166e+00 i +1.3632437e+00 4.7486705e+00 i +1.3726779e+00 4.9812724e+00 i +1.3821121e+00 5.2368151e+00 i +1.3915463e+00 5.5189212e+00 i +1.4009805e+00 5.8320185e+00 i +1.4104147e+00 6.1815765e+00 i +1.4198489e+00 6.5744321e+00 i +1.4292831e+00 7.0192453e+00 i +1.4387174e+00 7.5271504e+00 i +1.4481516e+00 8.1127075e+00 i +1.4575858e+00 8.7953302e+00 i +1.4670200e+00 9.6014914e+00 i +1.4764542e+00 1.0568253e+01 i +1.4858884e+00 1.1749150e+01 i +1.4953226e+00 1.3224482e+01 i +1.5047568e+00 1.5120436e+01 i +1.5141911e+00 1.7647326e+01 i +1.5236253e+00 2.1183712e+01 i +1.5330595e+00 2.6486718e+01 i +1.5424937e+00 3.5322963e+01 i +1.5519279e+00 5.2992306e+01 i +1.5613621e+00 1.0599405e+02 i +1.5707963e+00 1.6331239e+16 i +1.5802305e+00 -1.0599405e+02 i +1.5896648e+00 -5.2992306e+01 i +1.5990990e+00 -3.5322963e+01 i +1.6085332e+00 -2.6486718e+01 i +1.6179674e+00 -2.1183712e+01 i +1.6274016e+00 -1.7647326e+01 i +1.6368358e+00 -1.5120436e+01 i +1.6462700e+00 -1.3224482e+01 i +1.6557042e+00 -1.1749150e+01 i +1.6651384e+00 -1.0568253e+01 i +1.6745727e+00 -9.6014914e+00 i +1.6840069e+00 -8.7953302e+00 i +1.6934411e+00 -8.1127075e+00 i +1.7028753e+00 -7.5271504e+00 i +1.7123095e+00 -7.0192453e+00 i +1.7217437e+00 -6.5744321e+00 i +1.7311779e+00 -6.1815765e+00 i +1.7406121e+00 -5.8320185e+00 i +1.7500464e+00 -5.5189212e+00 i +1.7594806e+00 -5.2368151e+00 i +1.7689148e+00 -4.9812724e+00 i +1.7783490e+00 -4.7486705e+00 i +1.7877832e+00 -4.5360166e+00 i +1.7972174e+00 -4.3408168e+00 i +1.8066516e+00 -4.1609761e+00 i +1.8160858e+00 -3.9947221e+00 i +1.8255201e+00 -3.8405445e+00 i +1.8349543e+00 -3.6971490e+00 i +1.8443885e+00 -3.5634198e+00 i +1.8538227e+00 -3.4383899e+00 i +1.8632569e+00 -3.3212169e+00 i +1.8726911e+00 -3.2111639e+00 i +1.8821253e+00 -3.1075830e+00 i +1.8915595e+00 -3.0099027e+00 i +1.9009938e+00 -2.9176170e+00 i +1.9104280e+00 -2.8302756e+00 i +1.9198622e+00 -2.7474774e+00 i +1.9292964e+00 -2.6688632e+00 i +1.9387306e+00 -2.5941106e+00 i +1.9481648e+00 -2.5229297e+00 i +1.9575990e+00 -2.4550585e+00 i +1.9670332e+00 -2.3902602e+00 i +1.9764675e+00 -2.3283201e+00 i +1.9859017e+00 -2.2690426e+00 i +1.9953359e+00 -2.2122499e+00 i +2.0047701e+00 -2.1577794e+00 i +2.0142043e+00 -2.1054824e+00 i +2.0236385e+00 -2.0552227e+00 i +2.0330727e+00 -2.0068749e+00 i +2.0425069e+00 -1.9603240e+00 i +2.0519411e+00 -1.9154636e+00 i +2.0613754e+00 -1.8721959e+00 i +2.0708096e+00 -1.8304301e+00 i +2.0802438e+00 -1.7900824e+00 i +2.0896780e+00 -1.7510748e+00 i +2.0991122e+00 -1.7133352e+00 i +2.1085464e+00 -1.6767962e+00 i +2.1179806e+00 -1.6413953e+00 i +2.1274148e+00 -1.6070741e+00 i +2.1368491e+00 -1.5737781e+00 i +2.1462833e+00 -1.5414563e+00 i +2.1557175e+00 -1.5100612e+00 i +2.1651517e+00 -1.4795481e+00 i +2.1745859e+00 -1.4498751e+00 i +2.1840201e+00 -1.4210030e+00 i +2.1934543e+00 -1.3928947e+00 i +2.2028885e+00 -1.3655157e+00 i +2.2123228e+00 -1.3388330e+00 i +2.2217570e+00 -1.3128161e+00 i +2.2311912e+00 -1.2874357e+00 i +2.2406254e+00 -1.2626645e+00 i +2.2500596e+00 -1.2384766e+00 i +2.2594938e+00 -1.2148473e+00 i +2.2689280e+00 -1.1917536e+00 i +2.2783622e+00 -1.1691734e+00 i +2.2877965e+00 -1.1470859e+00 i +2.2972307e+00 -1.1254714e+00 i +2.3066649e+00 -1.1043110e+00 i +2.3160991e+00 -1.0835871e+00 i +2.3255333e+00 -1.0632825e+00 i +2.3349675e+00 -1.0433813e+00 i +2.3444017e+00 -1.0238681e+00 i +2.3538359e+00 -1.0047283e+00 i +2.3632701e+00 -9.8594788e-01 i +2.3727044e+00 -9.6751365e-01 i +2.3821386e+00 -9.4941292e-01 i +2.3915728e+00 -9.3163357e-01 i +2.4010070e+00 -9.1416404e-01 i +2.4104412e+00 -8.9699328e-01 i +2.4198754e+00 -8.8011069e-01 i +2.4293096e+00 -8.6350617e-01 i +2.4387438e+00 -8.4717000e-01 i +2.4481781e+00 -8.3109290e-01 i +2.4576123e+00 -8.1526596e-01 i +2.4670465e+00 -7.9968062e-01 i +2.4764807e+00 -7.8432870e-01 i +2.4859149e+00 -7.6920231e-01 i +2.4953491e+00 -7.5429388e-01 i +2.5047833e+00 -7.3959614e-01 i +2.5142175e+00 -7.2510210e-01 i +2.5236518e+00 -7.1080501e-01 i +2.5330860e+00 -6.9669840e-01 i +2.5425202e+00 -6.8277602e-01 i +2.5519544e+00 -6.6903186e-01 i +2.5613886e+00 -6.5546012e-01 i +2.5708228e+00 -6.4205520e-01 i +2.5802570e+00 -6.2881171e-01 i +2.5896912e+00 -6.1572442e-01 i +2.5991255e+00 -6.0278830e-01 i +2.6085597e+00 -5.8999849e-01 i +2.6179939e+00 -5.7735027e-01 i +2.6274281e+00 -5.6483909e-01 i +2.6368623e+00 -5.5246056e-01 i +2.6462965e+00 -5.4021039e-01 i +2.6557307e+00 -5.2808446e-01 i +2.6651649e+00 -5.1607875e-01 i +2.6745992e+00 -5.0418939e-01 i +2.6840334e+00 -4.9241261e-01 i +2.6934676e+00 -4.8074474e-01 i +2.7029018e+00 -4.6918223e-01 i +2.7123360e+00 -4.5772163e-01 i +2.7217702e+00 -4.4635959e-01 i +2.7312044e+00 -4.3509285e-01 i +2.7406386e+00 -4.2391822e-01 i +2.7500728e+00 -4.1283263e-01 i +2.7595071e+00 -4.0183305e-01 i +2.7689413e+00 -3.9091656e-01 i +2.7783755e+00 -3.8008029e-01 i +2.7878097e+00 -3.6932146e-01 i +2.7972439e+00 -3.5863735e-01 i +2.8066781e+00 -3.4802529e-01 i +2.8161123e+00 -3.3748270e-01 i +2.8255465e+00 -3.2700702e-01 i +2.8349808e+00 -3.1659578e-01 i +2.8444150e+00 -3.0624656e-01 i +2.8538492e+00 -2.9595696e-01 i +2.8632834e+00 -2.8572467e-01 i +2.8727176e+00 -2.7554739e-01 i +2.8821518e+00 -2.6542289e-01 i +2.8915860e+00 -2.5534898e-01 i +2.9010202e+00 -2.4532348e-01 i +2.9104545e+00 -2.3534428e-01 i +2.9198887e+00 -2.2540930e-01 i +2.9293229e+00 -2.1551649e-01 i +2.9387571e+00 -2.0566382e-01 i +2.9481913e+00 -1.9584931e-01 i +2.9576255e+00 -1.8607101e-01 i +2.9670597e+00 -1.7632698e-01 i +2.9764939e+00 -1.6661531e-01 i +2.9859282e+00 -1.5693413e-01 i +2.9953624e+00 -1.4728158e-01 i +3.0047966e+00 -1.3765581e-01 i +3.0142308e+00 -1.2805501e-01 i +3.0236650e+00 -1.1847738e-01 i +3.0330992e+00 -1.0892114e-01 i +3.0425334e+00 -9.9384519e-02 i +3.0519676e+00 -8.9865764e-02 i +3.0614019e+00 -8.0363137e-02 i +3.0708361e+00 -7.0874909e-02 i +3.0802703e+00 -6.1399361e-02 i +3.0897045e+00 -5.1934785e-02 i +3.0991387e+00 -4.2479479e-02 i +3.1085729e+00 -3.3031748e-02 i +3.1180071e+00 -2.3589905e-02 i +3.1274413e+00 -1.4152263e-02 i +3.1368755e+00 -4.7171411e-03 i +3.1463098e+00 4.7171411e-03 i +3.1557440e+00 1.4152263e-02 i +3.1651782e+00 2.3589905e-02 i +3.1746124e+00 3.3031748e-02 i +3.1840466e+00 4.2479479e-02 i +3.1934808e+00 5.1934785e-02 i +3.2029150e+00 6.1399361e-02 i +3.2123492e+00 7.0874909e-02 i +3.2217835e+00 8.0363137e-02 i +3.2312177e+00 8.9865764e-02 i +3.2406519e+00 9.9384519e-02 i +3.2500861e+00 1.0892114e-01 i +3.2595203e+00 1.1847738e-01 i +3.2689545e+00 1.2805501e-01 i +3.2783887e+00 1.3765581e-01 i +3.2878229e+00 1.4728158e-01 i +3.2972572e+00 1.5693413e-01 i +3.3066914e+00 1.6661531e-01 i +3.3161256e+00 1.7632698e-01 i +3.3255598e+00 1.8607101e-01 i +3.3349940e+00 1.9584931e-01 i +3.3444282e+00 2.0566382e-01 i +3.3538624e+00 2.1551649e-01 i +3.3632966e+00 2.2540930e-01 i +3.3727309e+00 2.3534428e-01 i +3.3821651e+00 2.4532348e-01 i +3.3915993e+00 2.5534898e-01 i +3.4010335e+00 2.6542289e-01 i +3.4104677e+00 2.7554739e-01 i +3.4199019e+00 2.8572467e-01 i +3.4293361e+00 2.9595696e-01 i +3.4387703e+00 3.0624656e-01 i +3.4482045e+00 3.1659578e-01 i +3.4576388e+00 3.2700702e-01 i +3.4670730e+00 3.3748270e-01 i +3.4765072e+00 3.4802529e-01 i +3.4859414e+00 3.5863735e-01 i +3.4953756e+00 3.6932146e-01 i +3.5048098e+00 3.8008029e-01 i +3.5142440e+00 3.9091656e-01 i +3.5236782e+00 4.0183305e-01 i +3.5331125e+00 4.1283263e-01 i +3.5425467e+00 4.2391822e-01 i +3.5519809e+00 4.3509285e-01 i +3.5614151e+00 4.4635959e-01 i +3.5708493e+00 4.5772163e-01 i +3.5802835e+00 4.6918223e-01 i +3.5897177e+00 4.8074474e-01 i +3.5991519e+00 4.9241261e-01 i +3.6085862e+00 5.0418939e-01 i +3.6180204e+00 5.1607875e-01 i +3.6274546e+00 5.2808446e-01 i +3.6368888e+00 5.4021039e-01 i +3.6463230e+00 5.5246056e-01 i +3.6557572e+00 5.6483909e-01 i +3.6651914e+00 5.7735027e-01 i +3.6746256e+00 5.8999849e-01 i +3.6840599e+00 6.0278830e-01 i +3.6934941e+00 6.1572442e-01 i +3.7029283e+00 6.2881171e-01 i +3.7123625e+00 6.4205520e-01 i +3.7217967e+00 6.5546012e-01 i +3.7312309e+00 6.6903186e-01 i +3.7406651e+00 6.8277602e-01 i +3.7500993e+00 6.9669840e-01 i +3.7595336e+00 7.1080501e-01 i +3.7689678e+00 7.2510210e-01 i +3.7784020e+00 7.3959614e-01 i +3.7878362e+00 7.5429388e-01 i +3.7972704e+00 7.6920231e-01 i +3.8067046e+00 7.8432870e-01 i +3.8161388e+00 7.9968062e-01 i +3.8255730e+00 8.1526596e-01 i +3.8350072e+00 8.3109290e-01 i +3.8444415e+00 8.4717000e-01 i +3.8538757e+00 8.6350617e-01 i +3.8633099e+00 8.8011069e-01 i +3.8727441e+00 8.9699328e-01 i +3.8821783e+00 9.1416404e-01 i +3.8916125e+00 9.3163357e-01 i +3.9010467e+00 9.4941292e-01 i +3.9104809e+00 9.6751365e-01 i +3.9199152e+00 9.8594788e-01 i +3.9293494e+00 1.0047283e+00 i +3.9387836e+00 1.0238681e+00 i +3.9482178e+00 1.0433813e+00 i +3.9576520e+00 1.0632825e+00 i +3.9670862e+00 1.0835871e+00 i +3.9765204e+00 1.1043110e+00 i +3.9859546e+00 1.1254714e+00 i +3.9953889e+00 1.1470859e+00 i +4.0048231e+00 1.1691734e+00 i +4.0142573e+00 1.1917536e+00 i +4.0236915e+00 1.2148473e+00 i +4.0331257e+00 1.2384766e+00 i +4.0425599e+00 1.2626645e+00 i +4.0519941e+00 1.2874357e+00 i +4.0614283e+00 1.3128161e+00 i +4.0708626e+00 1.3388330e+00 i +4.0802968e+00 1.3655157e+00 i +4.0897310e+00 1.3928947e+00 i +4.0991652e+00 1.4210030e+00 i +4.1085994e+00 1.4498751e+00 i +4.1180336e+00 1.4795481e+00 i +4.1274678e+00 1.5100612e+00 i +4.1369020e+00 1.5414563e+00 i +4.1463363e+00 1.5737781e+00 i +4.1557705e+00 1.6070741e+00 i +4.1652047e+00 1.6413953e+00 i +4.1746389e+00 1.6767962e+00 i +4.1840731e+00 1.7133352e+00 i +4.1935073e+00 1.7510748e+00 i +4.2029415e+00 1.7900824e+00 i +4.2123757e+00 1.8304301e+00 i +4.2218099e+00 1.8721959e+00 i +4.2312442e+00 1.9154636e+00 i +4.2406784e+00 1.9603240e+00 i +4.2501126e+00 2.0068749e+00 i +4.2595468e+00 2.0552227e+00 i +4.2689810e+00 2.1054824e+00 i +4.2784152e+00 2.1577794e+00 i +4.2878494e+00 2.2122499e+00 i +4.2972836e+00 2.2690426e+00 i +4.3067179e+00 2.3283201e+00 i +4.3161521e+00 2.3902602e+00 i +4.3255863e+00 2.4550585e+00 i +4.3350205e+00 2.5229297e+00 i +4.3444547e+00 2.5941106e+00 i +4.3538889e+00 2.6688632e+00 i +4.3633231e+00 2.7474774e+00 i +4.3727573e+00 2.8302756e+00 i +4.3821916e+00 2.9176170e+00 i +4.3916258e+00 3.0099027e+00 i +4.4010600e+00 3.1075830e+00 i +4.4104942e+00 3.2111639e+00 i +4.4199284e+00 3.3212169e+00 i +4.4293626e+00 3.4383899e+00 i +4.4387968e+00 3.5634198e+00 i +4.4482310e+00 3.6971490e+00 i +4.4576653e+00 3.8405445e+00 i +4.4670995e+00 3.9947221e+00 i +4.4765337e+00 4.1609761e+00 i +4.4859679e+00 4.3408168e+00 i +4.4954021e+00 4.5360166e+00 i +4.5048363e+00 4.7486705e+00 i +4.5142705e+00 4.9812724e+00 i +4.5237047e+00 5.2368151e+00 i +4.5331389e+00 5.5189212e+00 i +4.5425732e+00 5.8320185e+00 i +4.5520074e+00 6.1815765e+00 i +4.5614416e+00 6.5744321e+00 i +4.5708758e+00 7.0192453e+00 i +4.5803100e+00 7.5271504e+00 i +4.5897442e+00 8.1127075e+00 i +4.5991784e+00 8.7953302e+00 i +4.6086126e+00 9.6014914e+00 i +4.6180469e+00 1.0568253e+01 i +4.6274811e+00 1.1749150e+01 i +4.6369153e+00 1.3224482e+01 i +4.6463495e+00 1.5120436e+01 i +4.6557837e+00 1.7647326e+01 i +4.6652179e+00 2.1183712e+01 i +4.6746521e+00 2.6486718e+01 i +4.6840863e+00 3.5322963e+01 i +4.6935206e+00 5.2992306e+01 i +4.7029548e+00 1.0599405e+02 i +4.7123890e+00 5.4437465e+15 i + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfmanual-en-macros.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfmanual-en-macros.tex index 914383cdaf2..4033e67b27b 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfmanual-en-macros.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfmanual-en-macros.tex @@ -7,7 +7,7 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. -% $Header: /cvsroot/pgfplots/pgfplots/doc/latex/pgfplots/pgfmanual-en-macros.tex,v 1.3 2008/12/27 21:39:10 ludewich Exp $ +% $Header: /cvsroot/pgfplots/pgfplots/doc/latex/pgfplots/pgfmanual-en-macros.tex,v 1.4 2009/03/05 22:23:22 ludewich Exp $ % This file is part of the pgf manual; I re-use it here with @@ -395,6 +395,7 @@ \index{#1@\protect\texttt{#1} coordinate system}% \index{Coordinate systems!#1@\protect\texttt{#1}} \pgfmanualbody + \pgfmanualpdflabel{#1}{}% } { \end{pgfmanualentry} @@ -434,6 +435,7 @@ \ifx\pgfmanualtest\@empty% \index{#2@\protect\texttt{#2} path operation}% \index{Path operations!#2@\protect\texttt{#2}}% + \pgfmanualpdflabel{#2}{}% \fi% \pgfmanualbody } @@ -761,7 +763,7 @@ \catcode`\^^M=13 \catcode`\^^I=13 \catcode`\ =13% -\gdef\returntospace{\catcode`\ =13\def {\space}\catcode`\^^I=13\def^^I{\space}\catcode`\^^M=13\def^^M{}}% +\gdef\returntospace{\catcode`\ =13\def {\space}\catcode`\^^I=13\def^^I{\space}\catcode`\^^M=13\def^^M{\pgfkeysvalueof{/codeexample/newline}}}% \endgroup \begingroup @@ -840,10 +842,14 @@ code only/.code= {\code@executefalse}, pre/.code= {\def\code@pre{#1}}, post/.code= {\def\code@post{#1}}, + % #1 is the *complete* environment contents as it shall be + % typeset. In particular, the catcodes are NOT the normal ones. + typeset listing/.code= {#1}, vbox/.code= {\def\code@pre{\vbox\bgroup\setlength{\hsize}{\linewidth-6pt}}\def\code@post{\egroup}}, ignorespaces/.code= {\let\@gobble@till@return=\@gobble@till@return@ignore}, leave comments/.code= {\def\code@catcode@hook{\catcode`\%=12}\let\commenthandler=\relax\let\typesetcomment=\relax}, tabsize/.initial=0, + newline/.initial=, every codeexample/.style={width=4cm+7pt}, } @@ -939,7 +945,8 @@ \fi}% \obeylines \everypar \expandafter{\the\everypar \unpenalty}% - #1} + \pgfkeysvalueof{/codeexample/typeset listing/.@cmd}{#1}\pgfeov + } \end{minipage}}% \code@end% \par% diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex index ce1d14208bc..3db2099ab98 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots-macros.tex @@ -3,8 +3,139 @@ \input pgfmanual-en-macros.tex + +\def\pgfplotsifdocpackageuptodate#1#2{% + \pgfkeysifdefined{/codeexample/prettyprint/word/.@cmd}{#1}{#2} +}% + +\pgfplotsiffileexists{pgfmanual.sty}{% + \RequirePackage{pgfmanual} + \pgfplotsifdocpackageuptodate{}{% + \makeatletter + \input pgfplotsoldpgfsupp_pgfmanual.code.tex + \makeatother + }% +}{% + \makeatletter + \input pgfplotsoldpgfsupp_pgfmanual.code.tex + \makeatother +}% + + +\makeatletter +\def\pgfplotsmakefilelinkifuseful#1#2{% + \protect\pgfplotsmakefilelinkifuseful@{#1}{#2}% +}% +\def\pgfplotsmakefilelinkifuseful@#1#2{% + \edef\temp{#1}% + \edef\tempb{\jobname}% + \edef\temp{\meaning\temp}% \meaning normalizes the catcodes. + \edef\tempb{\meaning\tempb}% + \ifx\temp\tempb + % we are processing '#1'. Don't make a link. + #2% + \else + \href{file:#1.pdf}{#2}% + \fi +}% +\makeatother + + +\pgfkeys{ + /codeexample/prettyprint/cs arguments/pgfplotscreateplotcyclelist/.initial=2, + /codeexample/prettyprint/cs/pgfplotscreateplotcyclelist/.code args={#1#2#3}{\pgfmanualpdfref{#1}{#1}\{#2\}\{\pgfmanualprettyprintpgfkeys{#3}\pgfmanualclosebrace}, + /codeexample/prettyprint/cs arguments/tikzset/.initial=1, + /codeexample/prettyprint/cs/tikzset/.code 2 args={\pgfmanualpdfref{#1}{#1}\{\pgfmanualprettyprintpgfkeys{#2}\pgfmanualclosebrace}, + /codeexample/prettyprint/cs arguments/pgfplotsset/.initial=1, + /codeexample/prettyprint/cs/pgfplotsset/.code 2 args={\pgfmanualpdfref{#1}{#1}\{\pgfmanualprettyprintpgfkeys{#2}\pgfmanualclosebrace}, + /codeexample/prettyprint/cs arguments/pgfplotstableset/.initial=1, + /codeexample/prettyprint/cs/pgfplotstableset/.code 2 args={\pgfmanualpdfref{#1}{#1}\{\pgfmanualprettyprintpgfkeys{#2}\pgfmanualclosebrace}, + /codeexample/prettyprint/cs arguments/usepgfplotslibrary/.initial=1, + /codeexample/prettyprint/cs/usepgfplotslibrary/.code 2 args={\pgfmanualpdfref{#1}{#1}\{\pgfmanualpdfref{#2}{#2}\pgfmanualclosebrace}, + % + % + %/codeexample/prettyprint/key value/cycle list/.code 2 args={\pgfmanualprettyprintpgfkeys{#2}}, + /codeexample/prettyprint/key value/xticklabel/.code 2 args={\pgfmanualprettyprintcode{#2}}, + /codeexample/prettyprint/key value/yticklabel/.code 2 args={\pgfmanualprettyprintcode{#2}}, + /codeexample/prettyprint/key value/zticklabel/.code 2 args={\pgfmanualprettyprintcode{#2}}, + /codeexample/prettyprint/key value/includegraphics/.code 2 args={\pgfmanualprettyprintpgfkeys{#2}}, + % + % + % whenever an unqualified key is found, the following key prefix + % list is tried to find a match. + /pdflinks/search key prefixes in={/pgfplots/table/,/pgfplots/error bars/,/pgfplots/,/pgfplots/plot file/,/tikz/,/pgf/}, + % + % the link prefix written to the pdf file: + /pdflinks/internal link prefix=pgfp, + % + /pdflinks/warnings=false, + /pdflinks/codeexample links=true, + /pdflinks/show labels=false, +}% + + +% should be used to show something in red which doesn't need to get a +% hyper ref. +% +% Examples are descriptions of key labels. +\def\declaretext#1{\texttt{\declare{#1}}} + +% To be used whenever something NEW has been declared. +% In this case, a \pgfmanualpdflabel will be generated using '#1'. +% +% Use '\declaretext' if you only describe something local (for example +% the documentation of key values). +\def\declarelabel#1{% + \texttt{\declare{#1}}% + \pgfmanualpdflabel{#1}{}% +} + \def\pgfmanualbar{\char`\|} \makeatletter + +\newif\ifpgfplotsmanualexternalexpensive +\let\pgfplotsmanualexternalexpensivetrue@orig=\pgfplotsmanualexternalexpensivetrue + +% use \pgfplotsmanualexternalexpensivetrue to externalize expensive +% examples. +\def\pgfplotsmanualexternalexpensivetrue{% + \usepgfplotslibrary{external} + \pgfplotsmanualexternalexpensivetrue@orig + \tikzexternalize[ + prefix=figures/expensiveexample, + export=false, % needs to be activated for single pictures (i.e. expensive ones) + mode=list and make, + verbose IO=false, + %xport=true,% FASTER FOR DEBUGGING + ] + {pgfplots} + \tikzifexternalizing{% + \nofiles + \pgfkeys{/pdflinks/codeexample links=false}% + }{}% +}% + +\newif\ifpgfplots@example@is@expensive + +\pgfkeys{ + /codeexample/every codeexample/.append code={% + \ifpgfplots@example@is@expensive + \pgfkeys{/tikz/external/export=true}% + \global\pgfplots@example@is@expensivefalse + \fi + } +} + +% Write this macro directly in front of \begin{codeexample} (without arguments): +\def\pgfplotsexpensiveexample{% + \ifpgfplotsmanualexternalexpensive + \pgfplots@example@is@expensivetrue + \else + \message{[NOTE: I am now about to typeset an expensive example. You will need to ENLARGE YOUR TeX MEMORY CAPACITIES if this fails.]}% + \fi +}% + + \newenvironment{addplotoperation}[3][]{ \begin{pgfmanualentry} {% @@ -20,13 +151,90 @@ \declare{\texttt{#2}} \texttt{#3;}}% \unskip \nobreak - \pgfmanualentryheadline{\textcolor{gray}{{\texttt{\char`\\addplot}\oarg{style options} \texttt{plot}\oarg{behavior options}}\ }% + \pgfmanualentryheadline{\textcolor{gray}{\texttt{\char`\\addplot}\oarg{options} }% \declare{\texttt{#2}} \texttt{#3} \textcolor{gray}{\meta{trailing path commands}}\texttt{;}}% + \unskip + \nobreak + \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\addplot3}} $\dotsc$}% \def\pgfmanualtest{#1}% \ifx\pgfmanualtest\@empty% \index{#2@\protect\textcolor{gray}{\protect\texttt{plot}}\protect\texttt{ #2}}% \index{Plot operations!plot #2@\protect\texttt{plot #2}}% \fi% + \pgfmanualpdflabel{\textbackslash addplot #2}{}% + \pgfmanualpdflabel{plot #2}{}% + \pgfmanualpdflabel{#2}{}% + }% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{addplot+}{ + \begin{pgfmanualentry} + {% + \let\ltxdoc@marg=\marg + \let\ltxdoc@oarg=\oarg + \let\ltxdoc@parg=\parg + \let\ltxdoc@meta=\meta + \def\marg##1{{\normalfont\ltxdoc@marg{##1}}}% + \def\oarg##1{{\normalfont\ltxdoc@oarg{##1}}}% + \def\parg##1{{\normalfont\ltxdoc@parg{##1}}}% + \def\meta##1{{\normalfont\ltxdoc@meta{##1}}}% + \pgfmanualentryheadline{{\ttfamily\declare{\char`\\addplot+}\oarg{options} \textcolor{gray}{\dots};}}% + \index{addplot+@\protect\texttt{\protect\textbackslash addplot+}}% + \pgfmanualpdflabel{\textbackslash addplot+}{}% + }% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} +\newenvironment{addplot3generic}{ + \begin{pgfmanualentry} + {% + \let\ltxdoc@marg=\marg + \let\ltxdoc@oarg=\oarg + \let\ltxdoc@parg=\parg + \let\ltxdoc@meta=\meta + \def\marg##1{{\normalfont\ltxdoc@marg{##1}}}% + \def\oarg##1{{\normalfont\ltxdoc@oarg{##1}}}% + \def\parg##1{{\normalfont\ltxdoc@parg{##1}}}% + \def\meta##1{{\normalfont\ltxdoc@meta{##1}}}% + \pgfmanualentryheadline{{\ttfamily\declare{\char`\\addplot3}\oarg{options} \meta{input data} \meta{trailing path commands};}}% + \index{addplot3@\protect\texttt{\protect\textbackslash addplot3}}% + \pgfmanualpdflabel{\textbackslash addplot3}{}% + }% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} +\newenvironment{addplot3operation}[3][]{ + \begin{pgfmanualentry} + {% + \let\ltxdoc@marg=\marg + \let\ltxdoc@oarg=\oarg + \let\ltxdoc@parg=\parg + \let\ltxdoc@meta=\meta + \def\marg##1{{\normalfont\ltxdoc@marg{##1}}}% + \def\oarg##1{{\normalfont\ltxdoc@oarg{##1}}}% + \def\parg##1{{\normalfont\ltxdoc@parg{##1}}}% + \def\meta##1{{\normalfont\ltxdoc@meta{##1}}}% + \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\addplot3\ }}% + \declare{\texttt{#2}} \texttt{#3;}}% + \unskip + \nobreak + \pgfmanualentryheadline{\textcolor{gray}{\texttt{\char`\\addplot3}\oarg{options} }% + \declare{\texttt{#2}} \texttt{#3} \textcolor{gray}{\meta{trailing path commands}}\texttt{;}}% + \def\pgfmanualtest{#1}% + \ifx\pgfmanualtest\@empty% + \index{#2@\protect\texttt{#2}}% + \index{Plot operations!addplot3 #2@\protect\texttt{#2}}% + \fi% + \pgfmanualpdflabel{\textbackslash addplot3 #2}{}% + \pgfmanualpdflabel{plot3 #2}{}% }% \pgfmanualbody } @@ -36,7 +244,7 @@ \newenvironment{codekey}[1]{% \begin{pgfmanualentry} - \pgfmanualentryheadline{{\ttfamily\declare{#1}\textcolor{gray}{/.code}=\marg{...}}\hfill}% + \pgfmanualentryheadline{{\ttfamily\declare{#1}\textcolor{gray}{/\pgfmanualpdfref{/handlers/.code}{.code}}=\marg{...}}\hfill}% \def\mykey{#1}% \def\mypath{}% \def\myname{}% @@ -56,7 +264,7 @@ } \newenvironment{pgfplotscodetwokey}[1]{% \begin{pgfmanualentry} - \pgfmanualentryheadline{{\ttfamily\declare{/pgfplots/#1}\textcolor{gray}{/.code 2 args}=\marg{...}}\hfill}% + \pgfmanualentryheadline{{\ttfamily\declare{/pgfplots/#1}\textcolor{gray}{/\pgfmanualpdfref{/handlers/.code 2 args}{.code 2 args}}=\marg{...}}\hfill}% \def\mykey{/pgfplots/#1}% \def\mypath{}% \def\myname{}% @@ -75,7 +283,7 @@ \pgfmanualentryheadline@##1\pgfplots@EOI }% \def\pgfmanualentryheadline@##1\hfill##2\pgfplots@EOI{% - \oldpgfmanualentryheadline{{\ttfamily\declare{##1}\textcolor{gray}{/.code}=\marg{...}}\hfill}% + \oldpgfmanualentryheadline{{\ttfamily\declare{##1}\textcolor{gray}{/\pgfmanualpdfref{/handlers/.code}{.code}}=\marg{...}}\hfill}% } \begin{pgfplotsxykeylist}{#1}% } @@ -97,6 +305,8 @@ \newif\iffirstchoice \newcommand\mchoice[1]{% \begingroup + \let\margold=\marg + \def\marg##1{{\normalfont\margold{##1}}}% \firstchoicetrue \foreach \mchoice@ in {#1} {% \iffirstchoice @@ -109,6 +319,9 @@ \endgroup }% + + + % \begin{xykey}{/path/\x label=value} % \end{xykey} % @@ -157,11 +370,11 @@ \ifx\insertpathifneeded@@\empty \def\mykey{#1}% \else - \insertpathifneeded@#2\@nil + \insertpathifneeded@#1\@nil \ifpgfutil@in@ - \def\mykey{#2/#1}% - \else \def\mykey{#1}% + \else + \def\mykey{#2/#1}% \fi \fi }% @@ -196,6 +409,45 @@ \end{keylist}% } +\newenvironment{anchorlist}[1]{ + \begin{pgfmanualentry} + \foreach \xx in {#1} {% + \pgfmanualentryheadline{Anchor {\ttfamily\declare{\xx}}}% + \index{\xx @\protect\texttt{\xx} anchor}% + \index{Anchors!\xx @\protect\texttt{\xx}} + \expandafter\pgfmanualpdflabel\expandafter{\xx}{} + }% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + +\newenvironment{coordinatesystemlist}[1]{ + \begin{pgfmanualentry} + \foreach \xx in {#1} {% + \pgfmanualentryheadline{Coordinate system {\ttfamily\declare{\xx}}}% + \index{\xx @\protect\texttt{\xx} coordinate system}% + \index{Coordinate systems!\xx @\protect\texttt{\xx}} + \expandafter\pgfmanualpdflabel\expandafter{\xx}{} + }% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} +\renewenvironment{coordinatesystem}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{Coordinate system {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} coordinate system}% + \index{Coordinate systems!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{} + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + % \begin{xykeylist}[default path] % {/path/option \x1=value,/path/option \x2=value2,/path/option \x3=value} % \end{xykeylist} @@ -216,6 +468,31 @@ \end{pgfmanualentry} }% +\makeatother % FIXME this is almost surely a bug in pgfmanual-en-macros +% \begin{commandlist} +% {\command1{arg1},\command2{\arg2}} +% \end{commandlist} +\newenvironment{commandlist}[1]{% + \begin{pgfmanualentry} + \foreach \xx in {#1} {% + \expandafter\extractcommand\xx\@@% + }% + \pgfmanualbody +}{% + \end{pgfmanualentry} +}% + +\newenvironment{texif}[1]{% + \begin{pgfmanualentry} + \pgfmanualentryheadline{\declare{\texttt{\textbackslash if#1}}\meta{true code}\texttt{\textbackslash else}\meta{else code}\texttt{\textbackslash fi}}% + \index{if#1}% + \pgfmanualpdflabel{\\if#1}{}% + \pgfmanualbody +}{% + \end{pgfmanualentry} +}% +\makeatletter + \newif\ifxykeyfound \def\xykey@eq#1=#2\@nil{% @@ -232,6 +509,9 @@ \def\x{y}% \xdef\mykey{#1}% \expandafter\extractkey\mykey=#2\@nil% + \def\x{z}% + \xdef\mykey{#1}% + \expandafter\extractkey\mykey=#2\@nil% \fi } \def\xykey@noeq#1\@nil{% @@ -248,6 +528,9 @@ \def\x{y}% \xdef\mykey{#1}% \expandafter\extractkey\mykey\@nil% + \def\x{z}% + \xdef\mykey{#1}% + \expandafter\extractkey\mykey\@nil% \fi } @@ -271,11 +554,12 @@ } -\newenvironment{plottype}[1]{% - \begin{key}{/tikz/#1}% - \end{key} +% the first, optional argument is the default key path to insert. +\newenvironment{plottype}[2][/tikz]{% + \begin{keylist}[#1]{#2}% + \end{keylist} \begin{pgfmanualentry} - \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\addplot+[\declare{#1}]}}}% + \pgfmanualentryheadline{\textcolor{gray}{{\ttfamily\char`\\addplot+[\declare{#2}]}}}% \pgfmanualbody } { @@ -356,14 +640,15 @@ \pgfplotsassertcmdkeyexists{#1}% \pgfplotsassertcmdkeyexists{#2}% \begin{pgfplotskey}{#1=\marg{key-value-list}} - An abbreviation for \texttt{#2/.append style=}\marg{key-value-list}. + An abbreviation for \texttt{\pgfmanualpdfref{#2}{#2}/\pgfmanualpdfref{/handlers/.append style}{.append style}=}\marg{key-value-list}. \end{pgfplotskey} } \def\pgfplotsshortxystylekey #1=#2\pgfeov{% \pgfplotsassertXYcmdkeyexists{#1}% \pgfplotsassertXYcmdkeyexists{#2}% \begin{pgfplotsxykey}{#1=\marg{key-value-list}} - An abbreviation for {\def\x{x}\texttt{#2/.append style=}}\marg{key-value-list} (or the respective style for $y$, {\def\x{y}\texttt{#2}}). + An abbreviation for {\def\x{x}\texttt{\pgfmanualpdfref{#2}{#2}/\pgfmanualpdfref{/handlers/.append style}{.append style}=}}\marg{key-value-list} + (or the respective style for $y$, {\def\x{y}\texttt{\pgfmanualpdfref{#2}{#2}/\pgfmanualpdfref{/handlers/.append style}{.append style}=}}). \end{pgfplotsxykey} } \def\pgfplotsshortstylekeys #1,#2=#3\pgfeov{% @@ -373,7 +658,7 @@ \begin{pgfplotskeylist}{% #1=\marg{key-value-list}, #2=\marg{key-value-list}} - Different abbreviations for \texttt{#3/.append style=}\marg{key-value-list}. + Different abbreviations for \texttt{\pgfmanualpdfref{#3}{#3}/\pgfmanualpdfref{/handlers/.append style}{.append style}=}\marg{key-value-list}. \end{pgfplotskeylist} } \def\pgfplotsshortxystylekeys #1,#2=#3\pgfeov{% @@ -383,10 +668,31 @@ \begin{pgfplotsxykeylist}{% #1=\marg{key-value-list}, #2=\marg{key-value-list}} - Different abbreviations for {\def\x{x}\texttt{#3/.append style=}}\marg{key-value-list} (or the respective style for $y$, {\def\x{y}\texttt{#3}}). + Different abbreviations for {\def\x{x}\texttt{\pgfmanualpdfref{#3}{#3}/\pgfmanualpdfref{/handlers/.append style}{.append style}=}}\marg{key-value-list} + (or the respective style for $y$, {\def\x{y}\texttt{\pgfmanualpdfref{#3}{#3}/\pgfmanualpdfref{/handlers/.append style}{.append style}=}}). \end{pgfplotsxykeylist} } + +% +% For using the correct form of including libraries in the manual. +% +\newenvironment{pgfplotslibrary}[1]{% + \begin{pgfmanualentry} + \pgfmanualentryheadline{{\ttfamily\char`\\usepgfplotslibrary\char`\{\declare{#1}\char`\}\space\space \char`\%\space\space \LaTeX\space and plain \TeX}}% + \index{#1@\protect\texttt{#1} library}% + \index{Libraries!#1@\protect\texttt{#1}}% + \pgfmanualentryheadline{{\ttfamily\char`\\usepgfplotslibrary[\declare{#1}]\space \char`\%\space\space Con\TeX t}}% + \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary\char`\{\declare{pgfplots.#1}\char`\}\space\space \char`\%\space\space \LaTeX\space and plain \TeX}}% + \pgfmanualentryheadline{{\ttfamily\char`\\usetikzlibrary[\declare{pgfplots.#1}]\space \char`\%\space\space Con\TeX t}}% + \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + + % % Creates and shows a colormap with specification '#1'. \def\pgfplotsshowcolormapexample#1{% @@ -406,3 +712,74 @@ } \makeatother + +\def\decompose/#1/#2\nil{% + \def\test{#2}% + \ifx\test\empty% + % aha. + \index{#1@\protect\texttt{#1} key}% + \ifx\mypath\empty + \else + \index{\mypath#1@\protect\texttt{#1}}% + \fi + \def\myname{#1}% + %\pgfmanualpdflabel{#1}{}% No, its better to use fully qualified keys and search if necessary! + \else% + \iffirsttime + \begingroup + % also make a pdf link anchor with full key path. + \def\hyperlabelwithoutslash##1/\nil{% + \pgfmanualpdflabel{##1}{}% + }% + \hyperlabelwithoutslash/#1/#2\nil + \endgroup +% CF : disabled for /pgfplots/ prefix. +% \def\mypath{#1@\protect\texttt{/#1/}!}% +% \firsttimefalse + \def\pgfplotslocTMPa{pgfplots}% + \edef\pgfplotslocTMPb{#1}% + \ifx\pgfplotslocTMPb\pgfplotslocTMPa + \def\mypath{}% + \else + \def\mypath{#1@\protect\texttt{/#1/}!}% + \fi + \firsttimefalse + \else + \expandafter\def\expandafter\mypath\expandafter{\mypath#1@\protect\texttt{#1/}!}% + \fi + \def\firsttime{} + \decompose/#2\nil% + \fi% +} +\def\extracthandler#1#2\@nil{% + \pgfmanualentryheadline{Key handler \meta{key}{\ttfamily/\declare{#1}}#2}% + \index{\gobble#1@\protect\texttt{#1} handler}% + \index{Key handlers!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{/handlers/#1}% +} +\def\extractcommand#1#2\@@{% + \pgfmanualentryheadline{\declare{\texttt{\string#1}}#2}% + \removeats{#1}% + \index{\strippedat @\protect\myprintocmmand{\strippedat}}% + \pgfmanualpdflabel{\textbackslash\strippedat}{}% +} +\def\extractenvironement#1#2\@@{% + \pgfmanualentryheadline{{\ttfamily\char`\\begin\char`\{\declare{#1}\char`\}}#2}% + \pgfmanualentryheadline{{\ttfamily\ \ }\meta{environment contents}}% + \pgfmanualentryheadline{{\ttfamily\char`\\end\char`\{\declare{#1}\char`\}}}% + \index{#1@\protect\texttt{#1} environment}% + \index{Environments!#1@\protect\texttt{#1}}% + \pgfmanualpdflabel{#1}{}% +} +\renewenvironment{predefinednode}[1]{ + \begin{pgfmanualentry} + \pgfmanualentryheadline{Predefined node {\ttfamily\declare{#1}}}% + \index{#1@\protect\texttt{#1} node}% + \index{Predefined node!#1@\protect\texttt{#1}} + \pgfmanualpdflabel{#1}{}% + \pgfmanualbody +} +{ + \end{pgfmanualentry} +} + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex new file mode 100644 index 00000000000..950de93151b --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex @@ -0,0 +1,340 @@ +\section{Utilities and Basic Level Commands} +\label{sec:pgfplots:lowlevel} +This section documents commands which provide access to more basic elements of \PGFPlots. Most of them are closely related to the basic level of \pgfname, especially various point commands which are specific to an axis. Some of them are general purpose utilities like loops. + +However, most elements in this section are only interesting for advanced users -- and perhaps only for special cases. + +\subsection{Utitity Commands} + +\begin{command}{\foreach \meta{variables} |in| \meta{list} \marg{commands}} + A powerful loop command provided by \Tikz, see~\cite[Section Utilities]{tikz}. +\begin{codeexample}[] +\foreach \x in {1,2,...,4} {Iterating \x. }% +\end{codeexample} + + A \PGFPlots\ related example could be +\begin{codeexample}[code only] +\foreach \i in {1,2,...,10} {\addplot table {datafile\i}; }% +\end{codeexample} +\end{command} + +\begin{command}{\pgfplotsforeachungrouped \meta{variable} |in| \meta{list} \marg{command}} + A specialised variant of |\foreach| which can do two things: it does not introduce extra groups while executing \meta{command} and it allows to invoke the math parser for (simple!) \meta{$x_0$}|,|\meta{$x_1$}|,...,|\meta{$x_n$} expressions. + +\begin{codeexample}[] +\def\allcollected{} +\pgfplotsforeachungrouped \x in {1,2,...,4} {Iterating \x. \edef\allcollected{\allcollected, \x}}% +All collected = \allcollected. +\end{codeexample} + + A more useful example might be to work with tables. The following example is taken from \PGFPlotstable: + +\begin{codeexample}[code only] +\pgfplotsforeachungrouped \i in {1,2,...,10} {% + \pgfplotstablevertcat{\output}{datafile\i} % appends `datafile\i' -> `\output' +}% +% since it was ungrouped, \output is still defined (would not work +% with \foreach) +\end{codeexample} + + \paragraph{Remark: } The special syntax \meta{list}=\meta{$x_0$}|,|\meta{$x_1$}|,...,|\meta{$x_n$}, i.e.\ with two leading elements, followed by dots and a final element, invokes the math parser for the loop. Thus, it allows larger number ranges than any other syntax if |/pgf/fpu| is active. In all other cases, |\pgfplotsforeachungrouped| invokes |\foreach| and provides the results without \TeX\ groups. + +\end{command} + +\begin{command}{\pgfplotsinvokeforeach\marg{list} \marg{command}} + A variant of |\pgfplotsforeachungrouped| (and such also of |\foreach|) which replaces any occurence of |#1| inside of \meta{command} once for every element in \meta{list}. Thus, it actually assumes that \marg{command} is like a |\newcommand| body. + + In other words, \marg{command} is invoked for every element of \marg{list}. The actual element of \marg{list} is available as |#1|. + + As |\pgfplotsforeachungrouped|, this command does \emph{not} introduce extra scopes (i.e.\ it is ungrouped as well). + + The difference to |\foreach \x in |\meta{list}\marg{command} is subtle: the |\x| would \emph{not} be expanded whereas |#1| is. +\begin{codeexample}[] +\pgfkeys{ + otherstyle a/.code={[a]}, + otherstyle b/.code={[b]}, + otherstyle c/.code={[c]}, + otherstyle d/.code={[d]}} +\pgfplotsinvokeforeach{a,b,c,d} + {\pgfkeys{key #1/.style={otherstyle #1}}} +Invoke them: +\pgfkeys{key a} \pgfkeys{key b} +\pgfkeys{key c} \pgfkeys{key d} +\end{codeexample} +The counter example would use a macro (here |\x|) as loop argument: +\begin{codeexample}[] +\pgfkeys{ + otherstyle a/.code={[a]}, + otherstyle b/.code={[b]}, + otherstyle c/.code={[c]}, + otherstyle d/.code={[d]}} +\pgfplotsforeachungrouped \x in {a,b,c,d} + {\pgfkeys{key \x/.style={otherstyle \x}}} +Invoke them: +\pgfkeys{key a} \pgfkeys{key b} +\pgfkeys{key c} \pgfkeys{key d} +\end{codeexample} + + \paragraph{Restrictions:} you can't nest this command yet (since it does not introduce protection by scopes). +\end{command} + +\begin{command}{\pgfmathparse\marg{expression}} + Invokes the \pgfname\ math parser for \meta{expression} and defines \declareandlabel{\pgfmathresult} to be the result. +\begin{codeexample}[] +\pgfmathparse{1+41} + +The result is `\pgfmathresult'. +\end{codeexample} + Please refer to \cite{tikz} for more details. +\end{command} + + +\begin{command}{\pgfplotstableread\marg{file}} + Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle. +\end{command} +\begin{command}{\pgfplotstabletypeset\marg{\textbackslash macro}} + Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle. +\end{command} + +\begin{command}{\pgfplotsiffileexists\marg{filename}\marg{true code}\marg{false code}} + Invokes \marg{true code} if \marg{filename} exists and \marg{false code} if not. Can be used in looping macros, for example to plot every data file until there are no more of them. +\end{command} +\begin{command}{\pgfplotsutilifstringequal\marg{first}\marg{second}\marg{true code}\marg{false code}} + A simple ``strcmp'' tool which invokes \marg{true code} if \marg{first} $=$\marg{second} and \marg{false code} otherwise. This does not expand macros. +\end{command} + + +\begin{commandlist}{\pgfkeys,\pgfeov,\pgfkeysvalueof,\pgfkeysgetvalue} + These commands are part of the \Tikz\ way of specifying options, its sub-package |pgfkeys|. The |\pgfplotsset| command is actually nothing but a wrapper around |\pgfkeys|. + + A short introduction into |\pgfkeys| can be found in~\cite{keyvalintro} whereas the complete reference is, of course, the \Tikz\ manual~\cite{tikz}. + + The key |\pgfkeysvalueof|\marg{key name} expands to the value of a key; |\pgfkeysgetvalue|\marg{key name}\marg{\textbackslash macro} stores the value of \meta{key name} into \meta{\textbackslash macro}. The |\pgfeov| macro is used to delimit arguments for code keys in |\pgfkeys|, please refer to the references mentioned above. +\end{commandlist} + +\subsection[Commands Inside Of PGFPlots Axes]{Commands Inside Of {\normalfont\PGFPlots} Axes} +\begin{command}{\autoplotspeclist} +This command should no longer be used, although it will be kept as technical implementation detail. Please use the `|cycle list|' option, section~\ref{sec:cycle:list}. +\end{command} + +\begin{command}{\logten} +Expands to the constant $\log(10)$. Useful for logplots because $\log(10^i) = i\log(10)$. This command is only available inside of an \Tikz-picture. +\end{command} + +\begin{command}{\pgfmathprintnumber\marg{number}} +Generates pretty--printed output\footnote{This method was previously \texttt{\textbackslash prettyprintnumber}. It's functionality has been included into \PGF\ and the old command is now deprecated.} for \marg{number}. This method is used for every tick label. + +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}{\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. +\end{command} + +\begin{command}{\coordindex} + Inside of an |\addplot| command, this macro expands to the number of the actual coordinate (starting with~$0$). + + It is useful together with |x filter| or |y filter| to (de-)select coordinates. +\end{command} + +\subsection{Path Operations} + +\begin{commandlist}{\path,\draw,\fill,\node,\matrix} + These commands are \Tikz\ drawing commands all of which are documented in~\cite{tikz}. They are used to draw or fill paths, generate text nodes or aligned text matrizes. They are equivalent to + \pgfmanualpdflabel{/tikz/draw}{}|\path[draw]|, + \pgfmanualpdflabel{/tikz/fill}{}|\path[fill]|, + \pgfmanualpdflabel{/tikz/node}{}|\path[node]|, + \pgfmanualpdflabel{/tikz/matrix}{}|\path[matrix]|, + respectively. +\end{commandlist} +\begin{pathoperation}{--}{\meta{coordinate}} + A \Tikz\ path operation which connects the current point (the last one before |--|) and \meta{coordinate} with a straight line. +\end{pathoperation} +{\catcode`\|=12 +\begin{pathoperation}[noindex]{|-}{\meta{coordinate}} +\pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}% + A \Tikz\ path operation which connects the current point and \meta{coordinate} with \emph{two} straight lines: first vertical, then horizontal. +\end{pathoperation} + +\begin{pathoperation}[noindex]{-|}{\meta{coordinate}} +\pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}% + A \Tikz\ path operation which connects the current point and \meta{coordinate} with \emph{two} straight lines: first horizontal, then vertical. +\end{pathoperation} +} + +\begin{keylist}{/tikz/xshift=\marg{dimension},/tikz/yshift=\marg{dimension}} + These \Tikz\ keys allow to shift something by \marg{dimension} which is any \TeX\ size (or expression). +\end{keylist} + + +\begin{command}{\pgfplotsextra\marg{low-level path commands}} + A command to execute \marg{low-level path commands} in a \PGFPlots\ axis. Since any drawing commands inside of an axis need to be postponed until the axis is complete and the scaling has been initialised, it is not possible to simply draw any paths. + Instead, it is necessary to draw them as soon as the axis is finished. This is done automatically for every \Tikz\ path -- and it is also done manually if you write |\pgfplotsextra|\marg{commands}. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[xmin=0,xmax=3,ymin=0,ymax=5] + \pgfplotsextra{% + \pgfpathmoveto{\pgfplotspointaxisxy{1}{2}}% + \pgfpathlineto{\pgfplotspointaxisxy{2}{4}}% + \pgfusepath{stroke}% + } + \end{axis} +\end{tikzpicture} +\end{codeexample} + The example above initialises an axis and executes the basic level path commands as soon as the axis is ready. The execution of multiple |\path|, |\addplot| and |\pgfplotsextra| commands is in the same sequence as they occur in the environment\footnote{Except for stacked plots where the sequence may be reverse, see the key \texttt{reverse stack plots}.}.% +\end{command} + +\subsection{Specifying Basic Coordinates} + +\begin{commandlist}{% + \pgfplotspointaxisxy\marg{x coordinate}\marg{y coordinate},% + \pgfplotspointaxisxyz\marg{x coordinate}\marg{y coordinate}\marg{z coordinate}} + Point commands like |\pgfpointxy| which take logical, absolute coordinates and return a low--level point. Every transformation from user transformations to logarithms are applied. + + Since the transformations are initialised after the axis is complete, this command needs to be postponed (see |\pgfplotsextra|). +\end{commandlist} + +\begin{commandlist}{% + \pgfplotspointrelaxisxy\marg{rel x coordinate}\marg{rel y coordinate},% + \pgfplotspointrelaxisxyz\marg{rel x coordinate}\marg{rel y coordinate}\marg{rel z coordinate}} + Point commands which take \emph{relative} coordinates such that $x=0$ is the \emph{lower} $x$ axis limit and $x=1$ the \emph{upper} $x$ axis limit. + + These commands are used for |rel axis cs|. + + Please note that the transformations are only initialised if the axis is complete! This means you need to provide |\pgfplotsextra|. +\end{commandlist} + +\begin{commandlist}{% + \pgfplotspointdescriptionxy\marg{$x$ fraction}\marg{$y$ fraction},% + \pgfplotsqpointdescriptionxy\marg{$x$ fraction}\marg{$y$ fraction}}% + Point commands such that |{0}{0}| is the lower left corner of the axis' bounding box and |{1}{1}| the upper right one; everything else is in-between. The `|q|' variant is quicker as it doesn't invoke the math parser on its arguments. + + They are used for |axis description cs|, see section~\ref{pgfplots:sec:axis:description:cs}. +\end{commandlist} + +\begin{commandlist}{% + \pgfplotspointunitx,% + \pgfplotspointunity,% + \pgfplotspointunitz}% + Low--level point commands which return the $x$, $y$ or $z$ unit vectors. + + The point |\pgfplotspointxyz{1}{0}{0}| is the same as |\pgfplotspointunitx|, the |{0}{1}{0}| coordinate the unit $y$ vector and the |{0}{0}{1}| coordinate the unit $z$ vector. + + The unit $z$ vector is only defined for three dimensional axes. +\end{commandlist} + +\begin{commandlist}{% + \pgfplotsunitxlength,% + \pgfplotsunitylength,% + \pgfplotsunitzlength,% + \pgfplotsunitxinvlength,% + \pgfplotsunityinvlength,% + \pgfplotsunitzinvlength}% + Macros which expand to the vector length $\lVert x_i \rVert$ of the respective unit vector $x_i$ or the inverse vector length, $1/\lVert x_i \rVert$. These macros can be used inside of |\pgfmathparse|, for example. + + The $x_i$ are the |\pgfplotspointunitx| variants. +\end{commandlist} + +\begin{commandlist}{\pgfplotspointaxisorigin} + A point coordinate at the origin, $(0,0,0)$. If the origin is not part of the axis limits, the nearest point on the boundary is returned instead. + + This is the same coordinate as returned by the |origin| anchor. +\end{commandlist} + +\begin{command}{\pgfplotsqpointoutsideofaxis\marg{three-char-string}\marg{coordinate}\marg{normal distance}} + Provides a point coordinate on one of the available four axes in case of a two dimensional figure or on one of the available twelve axes in case of a three dimensional figure. + + The desired axis is uniquely identified by a three character string, provided as first argument to the command. The first of the three characters is `|0|' if the $x$ coordinate of the specified axis passes through the lower axis limit. It is `|1|', if the $x$ coordinate of the specified axis passes through the upper axis limit. Furthermore, it is `|2|' if it passes through the origin. The second character is also either |0|, |1| or |2| and it characterizes the position on the $y$ axis. The third character is for the third dimension, the $z$ axis. It should be left at `|0|' for two dimensional plots. However, \emph{one} of the three characters should be `|v|', meaning the axis \underline varies. For example, |v01| denotes $\{ (x,y_{\text{min}},z_{\text{max}}) \vert x \in \R \}$. + + The second argument, \meta{coordinate} is the logical coordinate on that axis. Since two coordinate of the axis are fixed, \meta{coordinate} refers to the \underline varying component of the axis. It must be a number without unit; no math expressions are supported here. + + The third argument \meta{normal distance} is a dimension like |10pt|. It shifts the coordinate away from the designated axis in direction of the outer normal vector. The outer normal vector always points away from the axis. It is computed using + |\pgfplotspointouternormalvectorofaxis|. + + There are several variants of this command which are documented in the source code. One of them is particularly useful: +\end{command} + +\begin{command}{\pgfplotsqpointoutsideofaxisrel\marg{three-char-string}\marg{axis fraction}\marg{normal distance}} + This point coordinate is a variant of |\pgfplotsqpointoutsideofaxis| which allows to provide an \meta{axis fraction} instead of an absolute coordinate. The fraction is a number between $0$ (lower axis limit) and $1$ (upper axis limit), i.e.\ it is given in percent of the total axis. It is possible to provide negative values or values larger than one. + + The |\pgfplotsqpointoutsideofaxisrel| command is similar in spirit to |rel axis cs|. + + There is one speciality in conjunction with reversed axes: if the axis has been reversed by |x dir=reverse| and, in addition, |allow reversal of rel axis cs| is true, the value $0$ denotes the \emph{upper} limit while $1$ denotes the \emph{lower} limit. The effect is that coordinates won't change just because of axis reversal. +\index{allow reversal of rel axis cs}% +\end{command} + +\begin{command}{\pgfplotspointouternormalvectorofaxis\marg{three-char-string}} + A point command which yields the outer normal vector of the respective axis. The normal vector has length $1$ (computed with |\pgfpointnormalised|). It is the same normal vector used inside of |\pgfplotsqpointoutsideofaxis| and its variants. + + The output of this command will be cached and re-used during the lifetime of an axis. +\end{command} + +\begin{command}{\pgfplotsticklabelaxisspec\marg{x, y or z}} + Expands to the three-character-identification for the axis containing tick labels for the chosen axis, either \meta{x}, \meta{y} or \meta{z}. +\end{command} + +\begin{command}{\pgfplotsvalueoflargesttickdimen\marg{x, y or z}} + Expands to the largest distance of a tick position to its tick label bounding box in direction of the outer unit normal vector. It does also include the value of the |ticklabel shift| key. + + This value is used for |ticklabel cs|. +\end{command} + +\begin{commandlist}{% + \pgfplotstransformcoordinatex\marg{x coordinate of an axis},% + \pgfplotstransformcoordinatey\marg{y coordinate of an axis},% + \pgfplotstransformcoordinatey\marg{z coordinate of an axis}} + Defines |\pgfmathresult| to be the low-level \PGF\ coordinate corresponding to the input argument. + + The command applies any |[xyz] coord trafo| keys, data scalings and/or logarithms or whatever \PGFPlots\ does to map input coordinates to internal coordinates. + + The result can be used inside of a |\pgfpointxy| statement (i.e.\ it still needs to be scaled with the respective \PGF\ unit vector). +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[xmin=0,xmax=2,ymin=0,ymax=5] + \pgfplotsextra{% + \pgfplotstransformcoordinatex{1}% + \let\xcoord=\pgfmathresult + \pgfplotstransformcoordinatey{1}% + \let\ycoord=\pgfmathresult + \pgfpathcircle + {\pgfqpointxy{\xcoord}{\ycoord}} + {5pt}% + \pgfusepath{fill}% + }% + \end{axis} +\end{tikzpicture} +\end{codeexample} + Please note that the transformations are only initialised if the axis is complete! This means you need to provide |\pgfplotsextra| as is shown in the example above. +\end{commandlist} + +\begin{command}{\pgfplotsconvertunittocoordinate\marg{x, y or z}\marg{dimension}} + Converts a dimension (with unit!) to a corresponding $x$, $y$ or $z$ coordinate. The result will be written to |\pgfmathresult| (without units). + + It is possible to use the result as arguments for the |\pgfpointxyz| commands. + + The effect is to multiply \marg{dimension} with the inverse length of the unit vector for the specified axis. These lengths are precomputed in \PGFPlots\ so the operation is fast. +\begin{codeexample}[code only] +\pgfplotsconvertunittocoordinate{x}{5pt} +% now, the command uses exactly 5pt in x direction: +\pgfqpointxyz{\pgfmathresult}{4}{3} +\end{codeexample} +\end{command} + +\begin{commandlist}{\pgfplotsmathfloatviewdepthxyz\marg{x}\marg{y}\marg{z}, + \pgfplotsmathviewdepthxyz\marg{x}\marg{y}\marg{z}} + Both macros define |\pgfmathresult| to be the ``depth'' of a three dimensional point $\bar x = (x,y,z)$. The depth is defined to be the scalar product of $\bar x$ with $\vec d$, the view direction of the current axis. + + For |\pgfplotsmathfloatviewdepthxyz|, the arguments are parsed as floating point numbers and the result is encoded in floating point. A fixed point representation can be generated with |\pgfmathfloattofixed{\pgfmathresult}|. + + For |\pgfplotsmathviewdepthxyz|, \TeX\ arithmetics is employed for the inner product and the result is assigned in fixed point. This is slightly faster, but has considerably smaller data range. + + Both commands can only be used \emph{inside} of a three dimensional \PGFPlots\ axis (as soon as the axis is initialised, see |\pgfplotsextra|). +\end{commandlist} + +\begin{texif}{pgfplotsthreedim} + A \TeX\ |\if| which evaluates the \meta{true code} if the axis is three dimensional and the \meta{else code} if not. +\end{texif} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.bib b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.bib index 0615f62d77c..62df0cd7b74 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.bib +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.bib @@ -24,3 +24,49 @@ title = {{PhP to javascript conversion project (GPL)}}, howpublished = {\url{http://kevin.vanzonneveld.net/techblog/article/phpjs_licensing}} } + + +@book{texbook, + author = {D. Knuth}, + title = {Computers \& Typesetting}, + publisher = {Addison Wesley}, + year = {2000} +} + + +@book{schwartz, + author = {N.~Schwartz}, + title = {{Einf\"uhrung in \TeX\ (german!)}}, + publisher = {Addison Wesley}, + year = {1991}, + note = {Also available online at \url{http://www.ruhr-uni-bochum.de/www-rz/schwanbs/TeX/} as \href{http://www.ruhr-uni-bochum.de/www-rz/schwanbs/TeX/einfuehrung-in-tex.pdf}{\texttt{.pdf}}} +} + +@misc{keyvalintro, + author = {J.~Wright and C.~Feuers\"anger}, + title = {Implementing keyval input: an introduction}, + howpublished = {{\url{http://pgfplots.sourceforge.net} as \href{http://www.morningstar2.demon.co.uk/papers/keyval.pdf}{\texttt{.pdf}}}}, + year = {2008} +} + +@misc{pgfplots, + author = {C.~Feuers\"anger}, + title = {{\PGFPlots\ manual}}, + year = {{\today}} +} + +@misc{pgfplotstable, + author = {C.~Feuers\"anger}, + title = {{\PGFPlotstable\ package -- Loading, rounding and formatting tables in LaTeX}}, + howpublished = {{Available as separate package \texttt{\textbackslash usepackage\{\href{file:pgfplotstable.pdf}{pgfplotstable}\}}}, as part of \PGFPlots}}, + year = {\today} +} + +@misc{programmingnotes, + author = {C.~Feuers\"anger}, + title = {{Programming in \TeX\ and Library Functions from \pgfname\ and \PGFPlots}}, + howpublished = {Available as part of \PGFPlots, \href{file:TeX-programming-notes.pdf}{TeX-programming-notes.pdf}}, + year = {\today} +} + + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist new file mode 100644 index 00000000000..acc4eee1e0f --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.figlist @@ -0,0 +1,47 @@ +figures/expensiveexamplepgfplots-figure0 +figures/expensiveexamplepgfplots-figure1 +figures/expensiveexamplepgfplots-figure2 +figures/expensiveexamplepgfplots-figure3 +figures/expensiveexamplepgfplots-figure4 +figures/expensiveexamplepgfplots-figure5 +figures/expensiveexamplepgfplots-figure6 +figures/expensiveexamplepgfplots-figure7 +figures/expensiveexamplepgfplots-figure8 +figures/expensiveexamplepgfplots-figure9 +figures/expensiveexamplepgfplots-figure10 +figures/expensiveexamplepgfplots-figure11 +figures/expensiveexamplepgfplots-figure12 +figures/expensiveexamplepgfplots-figure13 +figures/expensiveexamplepgfplots-figure14 +figures/expensiveexamplepgfplots-figure15 +figures/expensiveexamplepgfplots-figure16 +figures/expensiveexamplepgfplots-figure17 +figures/expensiveexamplepgfplots-figure18 +figures/expensiveexamplepgfplots-figure19 +figures/expensiveexamplepgfplots-figure20 +figures/expensiveexamplepgfplots-figure21 +figures/expensiveexamplepgfplots-figure22 +figures/expensiveexamplepgfplots-figure23 +figures/expensiveexamplepgfplots-figure24 +figures/expensiveexamplepgfplots-figure25 +figures/expensiveexamplepgfplots-figure26 +figures/expensiveexamplepgfplots-figure27 +figures/expensiveexamplepgfplots-figure28 +figures/expensiveexamplepgfplots-figure29 +figures/expensiveexamplepgfplots-figure30 +figures/expensiveexamplepgfplots-figure31 +figures/expensiveexamplepgfplots-figure32 +figures/expensiveexamplepgfplots-figure33 +figures/expensiveexamplepgfplots-figure34 +figures/expensiveexamplepgfplots-figure35 +figures/expensiveexamplepgfplots-figure36 +figures/expensiveexamplepgfplots-figure37 +figures/expensiveexamplepgfplots-figure38 +figures/expensiveexamplepgfplots-figure39 +figures/expensiveexamplepgfplots-figure40 +figures/expensiveexamplepgfplots-figure41 +figures/expensiveexamplepgfplots-figure42 +figures/expensiveexamplepgfplots-figure43 +figures/expensiveexamplepgfplots-figure44 +figures/expensiveexamplepgfplots-figure45 +figures/expensiveexamplepgfplots-figure46 diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex index e4d0099f383..070f573d1e2 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.importexport.tex @@ -1,150 +1,393 @@ -\section{Import/Export from other formats} +\section{Import/Export From Other Formats} \label{sec:pgfplots:importexport} This section contains information of how to single pictures into separate \pdf\ graphics files (or \eps\ graphics files). Furthermore, it explains a matlab (tm) script which allows to convert from matlab to \PGFPlots. \subsection[Export to pdf/eps]{Export to {\normalfont\pdf/\eps}} +\label{sec:pgfplots:export} It is possible to export images to single \pdf-documents using routines of \pgfname\ and/or \Tikz. -\subsubsection[Using the Externalization framework of pgf by hand]{Using the Externalization framework of {\normalfont\pgfname} ``by hand''} -The first way to export \TeX-pictures to single graphics files is to use the externalization framework of \pgfname. -The basic idea is to encapsulate the desired parts with +\subsubsection{Using the Automatic Externalization Framework of \Tikz} +\begin{pgfplotslibrary}{external} +\pgfkeys{ + /pdflinks/search key prefixes in/.add={/tikz/external/,}{} +} + The |external| library offers a convenient method to export every single |tikzpicture| into a separate~|.pdf| (or~|.eps|). Later runs of \LaTeX\ will simply include these graphics, thereby reducing typesetting time considerably. -|\beginpgfgraphicnamed|\marg{output file name} + The library can also be used to submit documents to authors who do not even have \PGFPlots\ or \Tikz\ installed. -\meta{picture contents} + \paragraph{Technical foreword:} + The |external| library has been written by Christian Feuers\"anger (author of \PGFPlots). It has been contributed to \Tikz\ as general purpose library, so the reference documentation along with all tweaks can be found in~\cite[Section ``Externalization Library'']{tikz}. The command |\usepgfplotslibrary{external}| is actually just a wrapper which loads |\usetikzlibrary{external}| or, if this library does not yet exist because the installed \pgfname\ has at most version $2.00$, it will load a copy which is shipped with \PGFPlots. -|\endpgfgraphicnamed|. + The |external| library has been designed such that \emph{no changes} to the document as such are necessary. The idea is as follows: +\begin{enumerate} + \item Every |\begin{tikzpicture}| $\dotsc$ |\end{tikzpicture}| gets a file name. The file name can be assigned manually with |\tikzsetnextfilename|\marg{output file name} or automatically, in which case \meta{tex file name}|-figure|\meta{number} is used with an increasing \meta{number}. + + \item The library writes the resulting images using system calls of the form |pdflatex --jobname |\marg{output file name} automatically, using the write18 system call of \TeX. It is the same framework which can be used to call |gnuplot|. +\end{enumerate} +The only steps which are necessary is to use -\noindent Furthermore, one needs to tell \pgfname\ the name of the main document using +\pgfmanualpdflabel{\textbackslash tikzexternalize}{}% +|\usepgfplotslibrary{external}| -|\pgfrealjobname|\marg{the real job's name} +|\tikzexternalize|\marg{the main file name} -\noindent in the preamble. This enables two different modes: -\begin{enumerate} - \item The first is the normal typesetting mode. \LaTeX\ checks whether a file named \marg{output file name} with one of the accepted file extensions exists -- if that is the case, the graphics file is included with |\pgfimage| and the \meta{picture contents} is skipped. If no such file exists, the \meta{picture contents} is typeset normally. This mode is applied if |\jobname| equals \marg{the real job's name}. - \item The second mode applies if |\jobname| equals \marg{output file name}, it initiates the ``conversion mode'' which is used to write the graphics file \marg{output file name}. In this case, \emph{only} \meta{picture contents} is written to |\jobname|, the complete rest of the \LaTeX\ is processed as normal, but it is silently discarded. - - This mode needs to be started manually with |pdflatex --jobname |\meta{output file name} for every externalized graphics file. -\end{enumerate} -A complete example may look as follows. +\noindent where \meta{the main file name} is the name of your |.tex| file (without the extension |.tex|). No further modification to the document is necessary. Suppose we have a file called |test.tex|: \begin{codeexample}[code only] \documentclass{article} \usepackage{pgfplots} -\pgfrealjobname{test} +\usepgfplotslibrary{external} +\tikzexternalize{test} \begin{document} \begin{figure} - \beginpgfgraphicnamed{testfigure} \begin{tikzpicture} \begin{axis} \addplot {x^2}; \end{axis} \end{tikzpicture} - \endpgfgraphicnamed \caption{Our first external graphics example} \end{figure} \begin{figure} - \beginpgfgraphicnamed{testfigure2} \begin{tikzpicture} \begin{axis} \addplot {x^3}; \end{axis} \end{tikzpicture} - \endpgfgraphicnamed \caption{A second graphics} \end{figure} \end{document} \end{codeexample} -\noindent The file is named |test.tex|, and it is processed (for example) with +\noindent To enable the system calls, we type \begin{codeexample}[code only] -pdflatex test +pdflatex -shell-escape test \end{codeexample} -\noindent Now, we type +\noindent and \LaTeX\ will now generate the required graphics files |test-figure0.pdf| and |test-figure1.pdf| automatically. Any further call to |pdflatex| will simply use |\includegraphics| and the |tikzpicture|s as such are no longer considered. + +If a figure shall be remade, one can simply delete all or selected graphics files and re-generate them. Alternatively, one can use the command |\tikzset{external/force remake}| somewhere in the document to remake every following picture automatically. + +There are three ways to modify the file names of externalized figures: +\begin{itemize} + \item Changing the overall file name using a |prefix|, + \item Changing the file name for a single figure using |\tikzsetnextfilename|, + \item Changing the file name for a restricted set of figures using |figure name|. +\end{itemize} +\begin{key}{/tikz/external/prefix=\marg{file name prefix} (initially empty)} + A shortcut for |\tikzsetexternalprefix|\marg{file name prefix}, see below. +\end{key} + +\begin{command}{\tikzsetexternalprefix\marg{file name prefix}} + Assigns a common prefix used by all file names. For example, \begin{codeexample}[code only] -pdflatex --jobname testfigure test -pdflatex --jobname testfigure2 test +\tikzsetexternalprefix{figures/} \end{codeexample} -\noindent to enter conversion mode. These last calls will \emph{only} write the contents of our named graphics environments, one for \marg{testfigure} and one for \marg{testfigure2} into the respective output files |testfigure.pdf| and |testfigure2.pdf|. + will prepend |figures/| to every external graphics file name. +\end{command} -In summary, one needs |\pgfrealjobname| and calls |pdflatex --jobname |\marg{graphics file} for every externalized graphics environment. Please note that it is absolutely necessary to use the syntax above, \emph{not} |\begin{pgfgraphicnamed}|. +\begin{command}{\tikzsetnextfilename\marg{file name}} + Sets the file name for the \emph{next} \tikzname\ picture or |\tikz| short command. It will \emph{only} be used for the next picture. -These steps are explained in much more detail in Section``Externalizing Graphics'' of~\cite{tikz}. This reference also contains information about how to typeset such a document without \pgfname\ installed. + Pictures for which no explicit file name has been set will get automatically generated file names. -I once attempted to write a unix \texttt{bash}--script |pgf2pdf.sh| which simplifies these steps in case that every externalized graphics environment is placed into a separate file |.pgf|. Interested readers find it in the installation tree. + Please note that |prefix| will still be prepended to \marg{file name}. +\begin{codeexample}[code only] +\documentclass{article} +% main document, called main.tex +\usepackage{tikz} -\paragraph{Attention:} Do not forget a correct |\pgfrealjobname| statement! If it is missing, externalization simply won't work. If it is wrong, any call to \LaTeX\ will produce empty output files. +\usepgfplotslibrary{external} +\tikzexternalize[prefix=figures/]{main} % provide the file's real name -\subsubsection{Using the automatic Externalization framework of \Tikz} -It is also possible to externalize graphics with the high-level library +\begin{document} -|\usetikzlibrary{external}| +\tikzsetnextfilename{firstplot} +\begin{tikzpicture} % will be written to 'figures/firstplot.pdf' +\begin{axis} + \addplot {x}; +\end{axis} +\end{tikzpicture} -\noindent which comes with (very recent versions of) \Tikz. At the time of this writing, it is \textbf{only available in the CVS~$2.0$ version of} \pgfname, sorry. It is a front-end for |\beginpgfgraphicnamed| which automatically encapsulates every picture in your document with the required externalization commands and performs commands to generate all required graphics files. -\begin{enumerate} - \item Every |\begin{tikzpicture}| $\dotsc$ |\end{tikzpicture}| gets a file name. The file name can be assigned manually with |\tikzsetnextfilename|\marg{output file name} or automatically, in which case \meta{tex file name}|-figure|\meta{number} is used with an increasing \meta{number}. +\begin{tikzpicture} % will be written to 'figures/main-figure0.pdf' + \draw[help lines] (0,0) grid (5,5); +\end{tikzpicture} +\end{document} +\end{codeexample} +\begin{codeexample}[code only] +pdflatex -shell-escape main +\end{codeexample} +\end{command} + +\begin{key}{/tikz/external/figure name=\marg{name}} + Same as |\tikzsetfigurename|\marg{name}. +\end{key} +\begin{command}{\tikzsetfigurename\marg{name}} + Changes the names of \emph{all} following figures. It is possible to change |figure name| during the document using |\tikzset{external/figure name|=\marg{name}|}|. A unique counter\footnote{These counters are stored into into different \emph{macros}. In other words: no \TeX\ register will be needed.} will be used for each different \marg{name}, and each counter will start at $0$. + + The value of |prefix| will be applied after |figure name| has been evaluated. +\begin{codeexample}[code only] +\documentclass{article} +% main document, called main.tex +\usepackage{tikz} + +\usepgfplotslibrary{external} +\tikzexternalize{main} % provide the file's real name + +\begin{document} + +% will be written to 'main-figure0.pdf' +\begin{tikzpicture} +\begin{semilogyaxis} + \addplot {exp(x)}; +\end{semilogyaxis} +\end{tikzpicture} + +{ + \tikzset{external/figure name={subset_}} + A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'subset_0.pdf' + + \begin{tikzpicture} % will be written to 'subset_1.pdf' + \begin{axis} + \addplot {x^2}; + \end{axis} + \end{tikzpicture} +}% here, the old file name will be restored: + +\begin{tikzpicture} % will be written to 'main-figure1.pdf' + \begin{axis} + \addplot[domain=1e-3:100] {1/x}; + \end{axis} +\end{tikzpicture} +\end{document} +\end{codeexample} + The scope of |figure name| ends with the next closing brace (as all values set by |\tikzset| do). + + \medbreak + Remark: Use |\tikzset{external/figure name/.add=|\marg{prefix}\marg{suffix}|}| to prepend a \meta{prefix} and append a \meta{suffix} to the actual value of |figure name|. Might be useful for something like +\begin{codeexample}[code only] +\tikzset{external/figure name=main} + +% uses main_0.pdf, main_1.pdf, ... + +\section{The first section} +{\tikzset{external/figure name/.add={}{_firstsection}} + ... + % uses main_firstsection_0.pdf, main_firstsection_1.pdf, ... +} + +\section{The second section} +{\tikzset{external/figure name/.add={}{secondsection_}} + ... + % uses main_secondsection_0.pdf, main_secondsection_1.pdf, ... + \subsection{Second subsection} + {\tikzset{external/figure name/.add={}{sub_}} + ... + % uses main_secondsection_sub_0.pdf, main_secondsection_sub_1.pdf, ... + } + % uses main_secondsection_2.pdf, main_secondsection_3.pdf, ... +} +\end{codeexample} +\end{command} + + +\begin{key}{/tikz/external/system call=\marg{template}} +\label{extlib:systemcall:option} + A template string used to generate system calls. Inside of \marg{template}, the macro |\image| can be used as placeholder for the image which is about to be generated while |\texsource| contains the main file name. + + The default is +\begin{codeexample}[code only] +\tikzset{external/system call={pdflatex -shell-escape -halt-on-error + -interaction=batchmode -jobname "\image" "\texsource"} +\end{codeexample} + + For |eps| output, you can (and need to) use +\begin{codeexample}[code only] +\tikzset{external/system call={latex -shell-escape -halt-on-error + -interaction=batchmode -jobname "\image" "\texsource"; + dvips -o "\image".ps "\image".dvi}} +\end{codeexample} - \item The library issues the required calls to |pdflatex --jobname |\marg{output file name} automatically, using the write18 system call of \TeX. It is the same framework which can be used to call |gnuplot|. -\end{enumerate} -The only steps which are necessary is to use + The argument \marg{template} will be expanded using |\edef|, so any control sequences will be expanded. During this evaluation, `|\\|' will result in a normal backslash, `|\|'. Furthermore, double quotes `|"|', single quotes `|'|', semicolons and dashes `|-|' will be made to normal characters if any package uses them as macros. This ensures compatibility with the |german| package, for example. +\end{key} -|\tikzexternalize|\marg{the job's real file name} +The complete reference documentation and remaining options are documented in~\cite[``Externalization Library'']{tikz}. This reference also contains information about +\begin{itemize} + \item how to use |\tikzset{external/|\declareandlabel{force remake}|}| and |\tikzset{external/|\declareandlabel{remake next}|}| to remake selected figures, + \item how to disable the externalization partially with |\tikzset{external/|\declareandlabel{export}|=false}| or completely with |\tikzexternaldisable|, + \item how to optimize the speed of the conversion process using |\tikzset{external/optimize command away=\myExpensiveMacro}|, + \item how to use |mode=list and make| to automatically generate makefiles for parallel image externalization\footnote{In case you'd like to test \texttt{list and make}, consider using \texttt{\textbackslash tikzifexternalizing\{\textbackslash nofiles\}\{\}} to suppress \texttt{.aux} file generation during parallel externalization procedures; \texttt{.aux} files would be screwed up otherwise.}, + \item how to typeset such a document without \pgfname\ installed or + \item how to provide work-arounds with |.pdf| images and bounding box restrictions. +\index{External Graphics!Bounding Box Issues} +\index{Bounding Box Control!Image Externalization Problems} +\end{itemize} + +\paragraph{Using the Library Without {\normalfont\pgfname} or {\normalfont\PGFPlots} Installed} +There is a small replacement package \declareandlabel{tikzexternal.sty} which can be used once every figure has been exported. The idea is to uncomment |\usepackage{tikz}| and |\usepackage{pgfplots}| and write |\usepackage{tikzexternal}| instead: +\begin{codeexample}[code only] +% \usepackage{tikz} +% \usepackage{pgfplots} +\usepackage{tikzexternal} +\tikzexternalize{test} % <-- provide the main .tex name + +\begin{document} +\begin{tikzpicture} + ... +\end{tikzpicture} +... +\end{document} +\end{codeexample} +You do not need \pgfname, \tikzname\ or \PGFPlots\ installed. What you need is |tikzexternal.sty| and all generated figures (consisting of the image files, `|.pdf|' and the `|.dpth|' files containing information of the |baseline| option). The file |tikzexternal.sty| is shipped with \pgfname\ in the directory +\begin{codeexample}[code only] +latex/pgf/utilities/tikzexternal.sty +\end{codeexample} +and a copy is shipped with \PGFPlots\ in +\begin{codeexample}[code only] +tex/generic/pgfplots/oldpgfcompatib/pgfplotsoldpgfsupp_tikzexternal.sty +\end{codeexample} +Just copy the file into your directory and rename it to |tikzexternal.sty|. + +\paragraph{Attention:} The small replacement package doesn't support key--value interfaces. Thus, it is necessary to use |\tikzsetexternalprefix| instead of the |prefix| option and |\tikzsetfigurename| instead of the |figure name| option since |\tikzset| is not available in such a context. Also, you may want to define a dummy--macro |\pgfplotsset| if you have used |\pgfplotsset|. +\end{pgfplotslibrary} + +\subsubsection[Using the Externalization Framework of PGF By Hand]{Using the Externalization Framework of {\normalfont\pgfname} ``By Hand''} +Another way to export \TeX-pictures to single graphics files is to use the externalization framework of \pgfname, which requires more work but works more generally than the |external| library. +The basic idea is to encapsulate the desired parts with + +\declareandlabel{\beginpgfgraphicnamed}\marg{output file name} + +\meta{picture contents} + +\declareandlabel{\endpgfgraphicnamed}. -\noindent as above. No further modification to the document is necessary. Now, the example file |test.tex| of the last subsection reads as follows: +\noindent Furthermore, one needs to tell \pgfname\ the name of the main document using + +\declareandlabel{\pgfrealjobname}\marg{the real job's name} + +\noindent in the preamble. This enables two different modes: +\begin{enumerate} + \item The first is the normal typesetting mode. \LaTeX\ checks whether a file named \marg{output file name} with one of the accepted file extensions exists -- if that is the case, the graphics file is included with |\pgfimage| and the \meta{picture contents} is skipped. If no such file exists, the \meta{picture contents} is typeset normally. This mode is applied if |\jobname| equals \marg{the real job's name}. + \item The second mode applies if |\jobname| equals \marg{output file name}, it initiates the ``conversion mode'' which is used to write the graphics file \marg{output file name}. In this case, \emph{only} \meta{picture contents} is written to |\jobname|, the complete rest of the \LaTeX\ is processed as normal, but it is silently discarded. + + This mode needs to be started manually with |pdflatex --jobname |\meta{output file name} for every externalized graphics file. +\end{enumerate} +A complete example may look as follows. \begin{codeexample}[code only] \documentclass{article} \usepackage{pgfplots} -\usetikzlibrary{external} -\tikzexternalize{test} +\pgfrealjobname{test} \begin{document} \begin{figure} + \beginpgfgraphicnamed{testfigure} \begin{tikzpicture} \begin{axis} \addplot {x^2}; \end{axis} \end{tikzpicture} + \endpgfgraphicnamed \caption{Our first external graphics example} \end{figure} \begin{figure} + \beginpgfgraphicnamed{testfigure2} \begin{tikzpicture} \begin{axis} \addplot {x^3}; \end{axis} \end{tikzpicture} + \endpgfgraphicnamed \caption{A second graphics} \end{figure} \end{document} \end{codeexample} -\noindent To enable the system calls, we type +\noindent The file is named |test.tex|, and it is processed (for example) with \begin{codeexample}[code only] -pdflatex -shell-escape test +pdflatex test \end{codeexample} -\noindent and \LaTeX\ will now generate the required graphics files |test-figure0.pdf| and |test-figure1.pdf| automatically. +\noindent Now, we type +\begin{codeexample}[code only] +pdflatex --jobname testfigure test +pdflatex --jobname testfigure2 test +\end{codeexample} +\noindent to enter conversion mode. These last calls will \emph{only} write the contents of our named graphics environments, one for \marg{testfigure} and one for \marg{testfigure2} into the respective output files |testfigure.pdf| and |testfigure2.pdf|. -The command |\tikzset{external/force remake}| somewhere in the document can be used to remake every following picture automatically. Of course, it is also possible to simply delete every graphics file. +In summary, one needs |\pgfrealjobname| and calls |pdflatex --jobname |\marg{graphics file} for every externalized graphics environment. Please note that it is absolutely necessary to use the syntax above, \emph{not} |\begin{pgfgraphicnamed}|. + +These steps are explained in much more detail in Section``Externalizing Graphics'' of~\cite{tikz}. -The library can also be configured to produce a list of figures in case system calls are undesired (or unavailable). In that case, |pdflatex --jobname |\marg{output file name} needs to be invoked for every file name listed in \meta{real file name}|.figlist|. This step can be done within a script. +\paragraph{Attention:} Do not forget a correct |\pgfrealjobname| statement! If it is missing, externalization simply won't work. If it is wrong, any call to \LaTeX\ will produce empty output files. -The command |\tikzsetexternalprefix|\marg{file prefix} can be used to prepend a directory name to every figure, for example with +It should be noted that this approach of image externalization is not limited to \Tikz\ picture environments. In fact, it collects everything between the begin and end statements into the external file. It is implicitly assumed that the encapsulated stuff is one box, but you can also encapsulate complete paragraphs using something like the \LaTeX\ minipage (or a |\vbox| which is not as powerful but does not affect the remaining document that much). + +\paragraph{Using the Library Without {\normalfont\pgfname} Installed} +Simply uncomment the packages |\usepackage{tikz}| and |\usepackage{pgfplots}| and use \begin{codeexample}[code only] -\tikzsetexternalprefix{figures/} +\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{% + \begingroup + \setbox1=\hbox{\includegraphics{#1}}% + \openin1=#1.dpth + \ifeof1 \box1 + \else + \read1 to\pgfincludeexternalgraphicsdp \closein1 + \dimen0=\pgfincludeexternalgraphicsdp\relax + \hbox{\lower\dimen0 \box1 }% + \fi + \endgroup +} \end{codeexample} -\noindent to produce |figures/test-figure0.pdf| and |figures/test-figure1.pdf| in our example. +instead. This will include the generated graphics files (and it will respect the |baseline| information stored in |.dpth| files). Consequently, you won't need \pgfname\ or \PGFPlots\ installed. See Section``Externalizing Graphics'' of~\cite{tikz} for details. -The complete reference documentation and remaining options are documented in the documentation for the ``PDF externalization library'' of~\cite{tikz}. This reference also contains information about how to typeset such a document without \pgfname\ installed or how to provide work-arounds with |.pdf| images and bounding box restrictions. -\index{External Graphics!Bounding Box Issues} -\index{Bounding Box Control!Image Externalization Problems} + +\subsection{Exporting Mesh Data From Matlab To \PGFPlots} +While it is easy to write Matlab vectors to files (using |save P.dat data -ASCII|), it is more involved to export mesh data. + +The main problem is to communicate the mesh structure to \PGFPlots. + +Here is an example how to realize this task: in Matlab, we have mesh data |X|, |Y| and |Z| which are matrizes of the same size. For example, suppose we have + +\begin{codeexample}[code only] +[X,Y] = meshgrid( linspace(-1,1,5), linspace(4,5,10) ); +Z = X + Y; +surf(X,Y,Z) +\end{codeexample} +\noindent as data. Then, we can generate an $N \times 3$ table containing all single elements in column--wise ordering with + +\begin{codeexample}[code only] +data = [ X(:) Y(:) Z(:) ] +save P.dat data -ASCII +\end{codeexample} +\noindent where the second command stores the $N \times 3$ table into |P.dat|. Finally, we can use + +|\addplot3[surf,mesh/rows=10,mesh/ordering=colwise,shader=interp] file {P.dat};| + +in \PGFPlots\ to read this data. We need to provide either the number of rows ($10$ here) or the number of columns -- and the ordering (which is |colwise| for Matlab matrizes). + +An alternative which is faster in \PGFPlots\ would be to transpose the matrizes in Matlab and tell \PGFPlots\ they are in |rowwise| ordering. So, the last step becomes + +\begin{codeexample}[code only] +XX=X'; YY=Y'; ZZ=Z'; +data = [ XX(:) YY(:) ZZ(:) ] +save P.dat data -ASCII +\end{codeexample} +\noindent with \PGFPlots\ command + +|\addplot3[surf,mesh/cols=10,mesh/ordering=rowwise,shader=interp] file {P.dat};|. \subsection{matlab2pgfplots.m} This is a Matlab (tm) script which attempts to convert a matlab figure to \PGFPlots. It requires Matlab version 7.4 (or higher). -The idea is to +\paragraph{Attention:} The author of \PGFPlots\ does not have enough time to maintain this script as much as he wants to. In other words, it supports only a small subset of \PGFPlots. You may also want to look at |matlab2tikz|, a conversion script of Nico Schl\"omer available at + +\url{http://www.mathworks.com/matlabcentral/fileexchange/22022-matlab2tikz} + +\noindent which also uses \PGFPlots\ for the \LaTeX\ conversion. + +\medskip +The idea of |matlab2pgfplots.m| is to \begin{itemize} \item use a complete matlab figure as input, \item acquire axis labels, axis scaling (log or normal) and legend entries, @@ -152,7 +395,7 @@ The idea is to \end{itemize} and write an equivalent \texttt{.pgf} file which typesets the plot with \PGFPlots. -The indention is \emph{not} to simulate matlab. It is a first step for a conversion. Type +The intention is \emph{not} to simulate matlab. It is a first step for a conversion. Type \begin{lstlisting} > help matlab2pgfplots \end{lstlisting} @@ -170,3 +413,6 @@ See matlab2pgfplots.m above. \subsection{SVG Output} It is possible to write every single \Tikz\ picture into a scalable vector graphics (\texttt{.svg}) file. This has nothing to do with \PGFPlots, it is a separate driver of \PGF. Please refer to~\cite[Section ``Producing HTML / SVG Output'']{tikz}. + +\subsection{Generate \PGFPlots\ Graphics Within Python} +Mario Orne D\'IAZ ANAD\'ON contributed a small python script |pgfplots.py| which provides a simple interface to generate \PGFPlots\ figures from within python. It can be found in the \PGFPlots\ installation directory, in |pgfplots/scripts/pgfplots/pgfplots.py|; documentation can be found in the file. diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.install.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.install.tex index 1e92392d3c3..851be797929 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.install.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.install.tex @@ -30,9 +30,19 @@ in your preamble (see section~\ref{sec:tex:dialects} for information about how t There are several ways how to teach \TeX\ where to find the files. Choose the option which fits your needs best. \subsubsection{Installation in Windows} -Windows users often use Mik\TeX\ which downloads the latest stable package versions automatically. As far as I know, you do not need to install anything manually here. However, Mik\TeX\ provides a feature to install packages locally in its own \TeX-Directory-Structure (TDS). This is the preferred way if you like to install newer version than those of Mik\TeX. The basic idea is to unzip \PGFPlots\ in a directory of your choice and use configure the Mik\TeX\ Package Manager to use this specific directory with higher priority than its default paths. +Windows users often use Mik\TeX\ which downloads the latest stable package versions automatically. You do not need to install anything manually here. + +However, Mik\TeX\ provides a feature to install packages locally in its own \TeX-Directory-Structure (TDS). This is the preferred way if you like to install newer version than those of Mik\TeX. The basic idea is to unzip \PGFPlots\ in a directory of your choice and configure the Mik\TeX\ Package Manager to use this specific directory with higher priority than its default paths. If you want to do this, start the Mik\TeX\ Settings using ``Start $\gg$ Programs $\gg$ Mik\TeX\ $\gg$ Settings''. There, use the ``Roots'' menu section. It contains the Mik\TeX\ Package directory as initial configuration. Use ``Add'' to select the directory in which the unzipped \PGFPlots\ tree resides. Then, move the newly added path to the list's top using the ``Up'' button. Then press ``Ok''. For Mik\TeX\ 2.8, you may need to uncheck the ``Show Mik\TeX-maintained root directories'' button to see the newly installed path. + +Mik\TeX\ complains if the provided directory is not TDS conform (see section~\ref{pgfplots:tds} for details), so you can't provide a wrong directory here. This method does also work for other packages, but some packages may need some directory restructuring before Mik\TeX\ accepts them. + +\subsubsection{Installation of Linux Packages} +At the time of this writing, I am unaware of \PGFPlots\ packages for recent stable Linux distributions. For Ubuntu, there are inofficial Ubuntu Package Repositories which can be added to the Ubuntu Package Tools. The idea is: add a simple URL to the Ubuntu Package Tool, run update and the installation takes place automatically. These URLs are maintained as PPA on Ubuntu Servers. + +The \PGFPlots\ download area on sourceforge contains recent links about Ubuntu Package Repositories, go to +\url{http://sourceforge.net/projects/pgfplots/files} +and download the readme files with recent links. -See also section~\ref{pgfplots:tds} for more information about separate TDS directories. \subsubsection{Installation in Any Directory - the \texttt{TEXINPUTS} Variable} You can simply install \PGFPlots\ anywhere on your disc, for example into @@ -55,17 +65,20 @@ so that the \TeX-documentation system finds the files |pgfplots.pdf| and |pgfplo Please refer to your operating systems manual for how to set environment variables. -\subsubsection{Installation Into a Local \texttt{texmf}-Directory} -Copy \PGFPlots\ to a local \texttt{texmf} directory like \lstinline!~/texmf! in your home directory. Then, install \PGFPlots\ into the subdirectory \lstinline!texmf/tex/generic/pgfplots! and run \lstinline!texhash!. - \subsubsection{Installation Into a Local TDS Compliant \texttt{texmf}-Directory} \label{pgfplots:tds} -A TDS conforming installation will use the same base directory as in the last section. Since \PGFPlots\ comes in TDS conforming directory structure, you can simply unpack the files into a directory of your choice and configure \TeX\ to use this directory as further include path. +\PGFPlots\ comes in a ``\TeX\ Directory Structure'' (TDS) conforming directory structure, so you can simply unpack the files into a directory which is searched by \TeX\ automatically. Such directories are |~/texmf| on Linux systems, for example. + +Copy \PGFPlots\ to a local \texttt{texmf} directory like \lstinline!~/texmf!. You need at least the \PGFPlots\ directories |tex/generic/pgfplots| and |tex/latex/pgfplots|. Then, run \lstinline!texhash! (or some equivalent path--updating command specific to your \TeX\ distribution). + +The TDS consists of several sub directories which are searched separately, depending on what has been requested: the sub-directories |doc/latex/|\meta{package} are used for (\LaTeX) documentation, the sub-directories |doc/generic/|\meta{package} for documentation which apply to \LaTeX\ and other \TeX\ dialects (like plain \TeX\ and Con\TeX t which have their own, respective sub-directories) as well. + +Similarly, the |tex/latex/|\meta{package} sub-directories are searched whenever \LaTeX\ packages are requested. The |tex/generic/|\meta{package} sub-directories are searched for packages which work for \LaTeX\ \emph{and} other \TeX\ dialects. Do not forget to run \lstinline!texhash!. \subsubsection{Installation If Everything Else Fails...} -If \TeX\ still doesn't find your files, you can copy all \lstinline!.sty! and all |.code.tex|-files into your current project's working directory. +If \TeX\ still doesn't find your files, you can copy all \lstinline!.sty! and all |.code.tex|-files (perhaps all |.def| files as well) into your current project's working directory. In fact, you need all which is in the |tex/latex/pgfplots| and |tex/generic/pgfplots| sub directories. Please refer to \url{http://www.ctan.org/installationadvice/} for more information about package installation. @@ -89,6 +102,7 @@ in most cases. It should work with any modern installation of \TeX\ (it activate The core mathematical engine of \PGF\ relies on \TeX\ registers to perform fast arithmetics. To compute $50+299$, it actually computes |50pt+299pt| and strips the |pt| suffix of the result. Since \TeX\ registers can only contain numbers up to $\pm 16384$, overflow error messages like ``Dimension too large'' occur if the result leaves the allowed range. Normally, this should never happen -- \PGFPlots\ uses a floating point unit with data range $\pm 10^{324}$ and performs all mappings automatically. However, there are some cases where this fails. Some of these cases are: \begin{enumerate} \item The axis range (for example, for $x$) becomes \emph{relatively} small. It's no matter if you have absolutely small ranges like $[10^{-17},10^{-16}]$. But if you have an axis range like $[1.99999999,2]$, where a lot of significant digits are necessary, this may be problematic. + \item This may happen as well if you only view a very small portion of the data range. \item The |axis equal| key will be confused if $x$ and $y$ have a very different scale. \item You may have found a bug -- please contact the developers. \end{enumerate} @@ -102,7 +116,9 @@ The core mathematical engine of \PGF\ relies on \TeX\ registers to perform fast \item \lstinline!pdflatex!, \item $\vdots$ \end{itemize} -However, there are some restrictions: I don't know any DVI viewer which is capable of viewing the output of \PGF\ (and therefor \PGFPlots\ as well). After all, DVI has never been designed to draw something different than text and horizontal/vertical lines. You will need to view the postscript file or the pdf-file. +However, there are some restrictions: I don't know any DVI viewer which is capable of viewing the output of \PGF\ (and therefor \PGFPlots\ as well). After all, DVI has never been designed to draw something different than text and horizontal/vertical lines. You will need to view the postscript file or the pdf-file. + +Then, the DVI/pdf combination doesn't support all types of shadings (for example, the |shader=interp| is only available for |dvips| and |pdftex| drivers). Furthermore, \PGF\ needs to know a \emph{driver} so that the DVI file can be converted to the desired output. Depending on your system, you need the following options: \begin{itemize} @@ -128,4 +144,10 @@ The choice which won't produce any problems at all is |pdflatex|. Both, \PGF\ and \PGFPlots\ use a lot of characters -- which may lead to incompatibilites with other packages which define active characters. Compatibility is better than in earlier versions, but may still be an issue. The manual compiles with the |babel| package for english and french, the |german| package does also work. If you experience any trouble, let me know. Sometimes it may work to disable active characters temporarily (|babel| provides such a command). \subsubsection{Other Problems} -Please contact the authors (preferrably by mail). Visit the webpages shown above to get contact information. +Please read the mailing list at + +\url{http://sourceforge.net/projects/pgfplots/support}. + +\noindent Perhaps someone has also encountered your problem before, and maybe he came up with a solution. + +Please write a note on the mailing list if you have a different problem. In case it is necessary to contact the authors directly, consider the addresses shown on the title page of this document. diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex index 3e4c4385723..af80b0ecd3f 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.intro.tex @@ -1,6 +1,6 @@ % main=pgfplots.tex -\section{Drawing axes and plots} +\section{User's Guide: Drawing Axes and Plots} \subsection{\TeX-dialects: \LaTeX, Con{\TeX}t, plain \TeX } \label{sec:tex:dialects}% \PGFPlots\ is compatible with \LaTeX, Con{\TeX}t and plain \TeX. The only difference is how to specify environments. This affects any \PGF/\Tikz-environments and all \PGFPlots-environments like axis, semilogxaxis, semilogyaxis and loglogaxis: @@ -33,9 +33,47 @@ \end{tabular}% } -A small \LaTeX--example file can be found in \begin{codeexample}[code only] -doc/latex/pgfplots/pgfplotsexample.tex. +\documentclass[a4paper]{article} + +% for dvipdfm: +%\def\pgfsysdriver{pgfsys-dvipdfm.def} +\usepackage{pgfplots} +\pgfplotsset{compat=newest}% <-- moves axis labels near ticklabels (respects tick label widths) + +\begin{document} +\begin{figure} + \centering + \begin{tikzpicture} + \begin{loglogaxis}[xlabel=Cost,ylabel=Error] + \addplot coordinates { + (5, 8.31160034e-02) + (17, 2.54685628e-02) + (49, 7.40715288e-03) + (129, 2.10192154e-03) + (321, 5.87352989e-04) + (769, 1.62269942e-04) + (1793, 4.44248889e-05) + (4097, 1.20714122e-05) + (9217, 3.26101452e-06) + }; + \addplot coordinates { + (7, 8.47178381e-02) + (31, 3.04409349e-02) + (111, 1.02214539e-02) + (351, 3.30346265e-03) + (1023, 1.03886535e-03) + (2815, 3.19646457e-04) + (7423, 9.65789766e-05) + (18943, 2.87339125e-05) + (47103, 8.43749881e-06) + }; + \legend{Case 1,Case 2} + \end{loglogaxis} + \end{tikzpicture} + \caption{A larger example} +\end{figure} +\end{document} \end{codeexample} \item[Con{\TeX}t:] |\usemodule[pgfplots]| and @@ -60,7 +98,7 @@ doc/latex/pgfplots/pgfplotsexample.tex. \end{tabular}% } -A small Con{\TeX}t--example file can be found in +A complete Con{\TeX}t--example file can be found in \begin{codeexample}[code only] doc/context/pgfplots/pgfplotsexample.tex. \end{codeexample} @@ -87,16 +125,16 @@ doc/context/pgfplots/pgfplotsexample.tex. \end{tabular}% } -A small plain--\TeX--example file can be found in +A complete plain--\TeX--example file can be found in \begin{codeexample}[code only] doc/plain/pgfplots/pgfplotsexample.tex. \end{codeexample} \end{description} -You may need to set low--level drivers if you intend to use |dvipdfm|, see section~\ref{sec:drivers}. +The default system drivers for |dvips| and |pdftex| work without any additional work; for |dvipdfm|, the |pgfsysdriver| macro needs to be redefined manually (see also section~\ref{sec:drivers}). -\subsection{A first plot} -Plotting is done using \lstinline|\begin{axis} ... \addplot ...; \end{axis}|, where |\addplot| is an interface to the \Tikz\ |plot| commands. +\subsection{A First Plot} +Plotting is done using \lstinline|\begin{axis} ... \addplot ...; \end{axis}|, where |\addplot| is the main interface to perform plotting operations. \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[ @@ -141,9 +179,9 @@ Plotting is done using \lstinline|\begin{axis} ... \addplot ...; \end{axis}|, wh \end{tikzpicture} \end{codeexample} -The |plot coordinates|, |plot gnuplot| and |plot expression| commands are three of the several supported ways to create plots, see section~\ref{sec:addplot} for more details\footnote{Please note that you need \lstinline{gnuplot} installed to use \lstinline{plot gnuplot}.} and the remaining ones (|plot file|, |plot table| and |plot graphics|). The options `|xlabel|' and `|ylabel|' define axis descriptions. +The |plot coordinates|, |plot expression| and |plot gnuplot| commands are three of the several supported ways to create plots, see section~\ref{sec:addplot} for more details\footnote{Please note that you need \lstinline{gnuplot} installed to use \lstinline{plot gnuplot}.} and the remaining ones (|plot file|, |plot shell|, |plot table| and |plot graphics|). The options `|xlabel|' and `|ylabel|' define axis descriptions. -\subsection{Two plots in the same axis} +\subsection{Two Plots in the Same Axis} Multiple |\addplot|-commands can be placed into the same axis. % generated with this statement: %\addplot plot[id=filesuffix_noise,domain=-6:5,samples=10] gnuplot{(-x**5 - 242 + (-300 + 600*rand(0)))}; @@ -155,7 +193,7 @@ Multiple |\addplot|-commands can be placed into the same axis. grid=major, ] - \addplot plot[id=filesuffix] gnuplot{(-x**5 - 242)}; + \addplot gnuplot[id=filesuffix]{(-x**5 - 242)}; \addlegendentry{model} \addplot coordinates { @@ -175,8 +213,8 @@ Multiple |\addplot|-commands can be placed into the same axis. \end{codeexample} A legend entry is generated if there are |\addlegendentry| commands (or one |\legend| command). -\subsection{Logarithmic plots} -Logarithmic plots show $\log x$ versus $\log y$ (or just one logarithmic axis). \PGFPlots\ always uses the natural logarithm, i.e. basis $e\approx2.718$. Now, the axis description also contains minor ticks and the labels are placed at $10^i$. +\subsection{Logarithmic Plots} +Logarithmic plots show $\log x$ versus $\log y$ (or just one logarithmic axis). \PGFPlots\ normally uses the natural logarithm, i.e. basis $e\approx2.718$ (see the key |log basis x|). Now, the axis description also contains minor ticks and the labels are placed at $10^i$. \begin{codeexample}[] \begin{tikzpicture} \begin{loglogaxis}[xlabel=Cost,ylabel=Gain] @@ -265,9 +303,10 @@ which is the same as |\begin{semilogyaxis}...\end{semilogyaxis}|. \end{tikzpicture}% \end{codeexample} -\subsection{Cycling line styles} +\subsection{Cycling Line Styles} You can skip the style arguments for |\addplot[...]| to determine plot specifications from a predefined list: \label{page:plotcoords:src}% +\pgfmanualpdflabel{\textbackslash plotcoords}{}% \begin{codeexample}[width=4cm] \begin{tikzpicture} \begin{loglogaxis}[ @@ -308,9 +347,9 @@ You can skip the style arguments for |\addplot[...]| to determine plot specifica \end{tikzpicture} \end{codeexample} \noindent -The cycle list can be modified, see the reference below. +The |cycle list| can be modified, see the reference below. -\subsection{Scaling plots} +\subsection{Scaling Plots} You can use any of the \Tikz\ options to modify the appearance. For example, the ``|scale|'' transformation takes the picture as such and scales it. \begin{codeexample}[] @@ -359,4 +398,6 @@ However, you can also scale plots by assigning a |width=5cm| and/or |height=3cm| \end{tikzpicture} \end{codeexample} +Use the predefined styles |normalsize|, |small|, |footnotesize| to adopt font sizes and ticks automatically. + \endinput diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex new file mode 100644 index 00000000000..056f80c7334 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.groupplot.tex @@ -0,0 +1,235 @@ +\subsection{Grouping plots} +\label{sec:group:plot} + +{\noindent {\emph{by Nick Papior Andersen}}} + +\index{Group library!Subplots}% + + +\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. +\end{pgfplotslibrary} + +\begin{environment}{{groupplot}\oarg{options}} + Once you have loaded the |groupplots| library you will gain access to this environment. This environment is limited to the same restrictions as the + |axis| environment. It actually utilizes this environment so consider it as an extension of this. What is important to note is that \oarg{options} gets + applied to all plots in the entire environment. This can be really handy when you need the same |xmin|, |xmax|, |ymin| and |ymax|. +\end{environment} + +With such an environment one can typeset plots in matrix like styles +% \usepgfplotslibrary{groupplots} +\begin{codeexample}[] +% Example using groupplots library +\begin{tikzpicture} + \begin{groupplot}[group style={group size=2 by 2},height=3cm,width=3cm] + \nextgroupplot + \addplot coordinates {(0,0) (1,1) (2,2)}; + \nextgroupplot + \addplot coordinates {(0,2) (1,1) (2,0)}; + \nextgroupplot + \addplot coordinates {(0,2) (1,1) (2,1)}; + \nextgroupplot + \addplot coordinates {(0,2) (1,1) (1,0)}; + \end{groupplot} +\end{tikzpicture} +% Same example created as done without the library +\begin{tikzpicture} + \begin{axis}[name=plot1,height=3cm,width=3cm] + \addplot coordinates {(0,0) (1,1) (2,2)}; + \end{axis} + \begin{axis}[name=plot2,at={($(plot1.east)+(1cm,0)$)},anchor=west,height=3cm,width=3cm] + \addplot coordinates {(0,2) (1,1) (2,0)}; + \end{axis} + \begin{axis}[name=plot3,at={($(plot1.south)-(0,1cm)$)},anchor=north,height=3cm,width=3cm] + \addplot coordinates {(0,2) (1,1) (2,1)}; + \end{axis} + \begin{axis}[name=plot4,at={($(plot2.south)-(0,1cm)$)},anchor=north,height=3cm,width=3cm] + \addplot coordinates {(0,2) (1,1) (1,0)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +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}} +\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. +The order in which figures are typeset are as seen in the next example. +% \usepgfplotslibrary{groupplots} +\begin{codeexample}[] +\begin{tikzpicture}[shorten >=4pt,shorten <=4pt] + \begin{groupplot}[group style={group size=2 by 2}, + height=3.5cm,width=3.5cm,/tikz/font=\small] + \nextgroupplot%1 + \addplot coordinates {(0,1) (1,0)}; + \nextgroupplot%2 + \addplot coordinates {(0,1) (1,0)}; + \nextgroupplot%3 + \addplot coordinates {(0,1) (1,0)}; + \nextgroupplot%4 + \addplot coordinates {(0,1) (1,0)}; + \end{groupplot} + \draw[thick,>=latex,->,red] + (group c1r1.center) node {1.} -- + (group c2r1.center) node {2.}; + \draw[thick,>=latex,->,red] + (group c2r1.center) -- + (group c1r2.center) node {3.}; + \draw[thick,>=latex,->,red] + (group c1r2.center) -- + (group c2r2.center) node {4.}; +\end{tikzpicture} +\end{codeexample} +The plot first fills the first row, then the next row and so on. Just like a table, thus the names |group c|\meta{column}|r|\meta{row}. The power of the |groupplot| is +to quickly create an aligned structure of plots. But you can also utilize it to structure data more creatively. Consider the next example. +% \usepgfplotslibrary{groupplots} +\begin{codeexample}[] +\begin{tikzpicture} + \begin{groupplot}[group style={group size=2 by 2, + horizontal sep=0pt,vertical sep=0pt, + xticklabels at=edge bottom}, + xmin=0,ymin=0, + height=3.7cm,width=4cm,no markers] + \nextgroupplot[group/empty plot] + \nextgroupplot[xmin=5,xmax=10,ymin=50,ymax=100] + \addplot[very thick] file {plotdata/group-1.dat}; + \nextgroupplot[xmax=5,ymax=50] + \addplot[very thick] file {plotdata/group-1.dat}; + \nextgroupplot[xmin=5,xmax=10,ymax=50,yticklabels={}] + \addplot[very thick] file {plotdata/group-1.dat}; + \end{groupplot} +\end{tikzpicture} +\end{codeexample} + +Or for instance zooming in on data as in the next example. +% \usepgfplotslibrary{groupplots} +\begin{codeexample}[] +\begin{tikzpicture} + \begin{groupplot}[group style={group size=3 by 1},xmin=0,ymin=0,height=4cm,width=5cm,no markers] + \nextgroupplot + \addplot[very thick] file {plotdata/group-1.dat}; + \draw[red,dashed,thick] (axis cs:0,0) rectangle (axis cs:5,30); + \nextgroupplot[xmax=5,ymax=30] + \addplot[very thick] file {plotdata/group-1.dat}; + \draw[red,dashed,thick] (axis cs:3,10) rectangle (axis cs:5,25); + \nextgroupplot[xmin=3,xmax=5,ymin=10,ymax=25] + \addplot[very thick] file {plotdata/group-1.dat}; + \end{groupplot} + \draw[thick,blue,->,shorten >=2pt,shorten <=2pt] + (group c1r1.east) -- (group c2r1.west); + \draw[thick,blue,->,shorten >=2pt,shorten <=2pt] + (group c2r1.east) -- (group c3r1.west); +\end{tikzpicture} +\end{codeexample} +\end{command} + + +\subsubsection{Grouping options} +\label{sec:pgfplots:group:options} + +Here the various available options of the library resides. + +\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. +\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|. + +\begin{pgfplotskeylist}{group/group size=\meta{columns} by \meta{rows} (initially 1 by 1), + 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 + the key |group size| uses |columns| and |rows| you should stick to either |group size| or both |columns| and |rows|. +\end{pgfplotskeylist} + +\begin{pgfplotskeylist}{group/horizontal sep=\meta{dimension} (initially 1cm), + group/vertical sep=\meta{dimension} (initially 1cm)} + The spacing between the plots in the horizontal and vertical direction, respectively. If you thus want them to be \textit{glued} together you should set + them both to a length of |0pt|. +\end{pgfplotskeylist} + +\begin{pgfplotskey}{group/every plot/.style=\marg{style} (initially empty)} + 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)} + 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 + +\begin{codeexample}[code only] +\pgfplotsset{group/xticklabels at=edge bottom,group/yticklabels at=edge right} +\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. +\end{pgfplotskeylist} + +\begin{pgfplotskey}{group/group name=\marg{name} (initially group)} + This sets what you can refer the plots to after typesetting. Thus you can use their anchors later. See the following example +% \usepgfplotslibrary{groupplots} +\begin{codeexample}[] +\begin{tikzpicture} + \begin{groupplot}[group style={ + group name=my plots,group size=2 by 2}, + width=4cm,height=4cm] + \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} + \draw (my plots c1r1.east) + circle (3pt) node {East}; + \draw (my plots c2r1.north) + circle (3pt) node {north}; + \draw (my plots c1r2.center) + circle (3pt) node {center}; + \draw (my plots c2r2.north west) + circle (3pt) node {North west}; +\end{tikzpicture} +\end{codeexample} +\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 + 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}[] +\begin{tikzpicture} + \begin{groupplot}[group style={ + group name=my plots,group size=2 by 2}, + width=4cm,height=4cm] + \nextgroupplot[group/empty plot] + \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} + \draw (my plots c1r1.east) + circle (3pt) node {East}; + \draw (my plots c2r1.north) + circle (3pt) node {north}; + \draw (my plots c1r2.center) + circle (3pt) node {center}; + \draw (my plots c2r2.north west) + 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. +\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 0c49dd0b0be..44ff66ca55c 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.tex @@ -1,22 +1,22 @@ \section{Related Libraries} This section describes some libraries which come with \PGFPlots, but they are more or less special and need to be activated separately. +\pgfmanualpdflabel{\textbackslash usepgfplotslibrary}{} \subsection{Dates as Input Coordinates} -\begin{tikzlibrary}{dateplot} - A library which allows to use dates like |2008-01-01| as input coordinates in plots. The library converts dates to numbers and tick labels will be pretty-printed dates. +\begin{pgfplotslibrary}{dateplot} + A library which allows to use dates like |2008-01-01| or dates with time like |2008-01-01 11:35| as input coordinates in plots. The library converts dates to numbers and tick labels will be pretty-printed dates (or times). This library is documented in section~\ref{pgfplots:sec:symbolic:coords} on page~\pageref{pgfplots:sec:date:coords}. -\end{tikzlibrary} +\end{pgfplotslibrary} \subsection{Clickable Plots} -\begin{tikzlibrary}{pgfplotsclickable} +\begin{pgfplotslibrary}{clickable} A library which generates small popups whenever one clicks into a plot. The popup displays the coordinate under the mouse pointer. Furthermore, the library allows to display slopes if one holds the mouse pressed and drags it to another point in the plot. - Although this library has been written for \PGFPlots, it can be used independently of an \PGFPlots\ environment. - It is completely sufficient to write + It is completely sufficient to write \begin{codeexample}[code only] -\usetikzlibrary{pgfplotsclickable} +\usepgfplotslibrary{clickable} \end{codeexample} \noindent in the document preamble. This will automatically prepare every plot. @@ -25,13 +25,30 @@ This section describes some libraries which come with \PGFPlots, but they are mo \includegraphics[height=6cm]{figures/pgfplotsclickable-fig1.png} \rlap{\includegraphics[height=6cm]{figures/pgfplotsclickable-fig2.png}}\hfill - \includegraphics[height=6cm]{figures/pgfplotsclickable-fig3.png} - \rlap{\includegraphics[height=6cm]{figures/pgfplotsclickable-fig4.png}}\hfill + \nobreak + These screenshots show the result of clicking into the axis range (left column) and of dragging from one point to another (right column). The second case shows the result of drag- and drop: it displays start- and end points and the equation for the line segment between between the first point of the drag- and drop and the second point where the mouse has been released. The line segment is + \[ l(x; x_0,y_0,x_1,y_1) = m \cdot x + n \] + where $m = (y_1-y_0) / (x_1-x_0)$ is the slope and $n$ the offset chosen such that $l(x_0;\dotsc) = y_0$. For logarithmic plots, logarithms will be applied before computing slopes. + + \noindent + \hbox to \linewidth{% + \hspace{-0.5cm}% + \begin{tikzpicture} + \node at (8cm,0cm) {\includegraphics[height=6cm]{figures/pgfplotsclickable-fig4.png}}; + \node at (0cm,0cm) {\includegraphics[height=6cm]{figures/pgfplotsclickable-fig3.png}}; + \end{tikzpicture}\hss}% \nobreak - These screenshots show the result of clicking into the axis range (left column) and of dragging from one point to another (right column). The second case shows start- and end points and the slope of the line segment in--between. + These screenshots show the result of drag- and drop for \emph{logarithmic} axes: the end points show, again, the coordinates (without logs) and the form field in the middle shows the slope and offset of the linear equation in log coordinates. + + The log basis for any logarithmic axes is usually~$10$, but it respects the current setting of |log basis x| and |log basis y|. The applied log will always use the same logarithm which is also used for the axis descriptions (this is not necessarily the same as used by \PGFPlotstable!). - This document has been produces with |pgfplotsclickable|, so it is possible to load it into Acrobat Reader and simply click into a plot. + This document has been produced with the |clickable| library, so it is possible to load it into Acrobat Reader and simply click into a plot. + + \expandafter\ifx\csname pgfplotsclickabledisabled\endcsname\relax + \else + \paragraph{Attention:} For this document, the |clickable| library has been deactivated. You may find a different version on \url{http://sourceforge.net/projects/pgfplots}. + \fi A click places an annotation at the coordinate under the mouse pointer, a snap--to--nearest feature is not available (yet?). @@ -42,6 +59,7 @@ This section describes some libraries which come with \PGFPlots, but they are mo \item At the time of this writing, only Adobe Acrobat Reader interpretes Javascript and Forms properly. The library doesn't have any effect if the resulting document is used in other viewers (as far as I know). \end{itemize} + Note that although this library has been written for \PGFPlots, it can be used independently of an \PGFPlots\ environment. \paragraph{Compatibility issues:} There a several restrictions when using this library. Most of them will vanish in future versions -- but up to now, I can't do magic. @@ -49,11 +67,18 @@ 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 in conjunction with the 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. + As long as you are working on a draft version of your document, you might want to use +\begin{codeexample}[code only] +\pgfkeys{/pgf/images/include external/.code={\href{file:#1}{\pgfimage{#1}}} +\end{codeexample} + in your preamble. This will generate hyper links around the graphics files which link to the exported figures. Clicking on the hyper links opens the exported figure which, in turn, has been generated with the |clickable| library and allows dynamic features\footnote{This special treatment needs the external files in the same base directory as the main document, so this approach is most certainly \emph{not} suitable for a final document.}. + + \item The library automatically calls |\begin{Form}| at |\begin{document}| and |\end{Form}| at the end of the document. This environment of |hyperref| is necessary for dynamic user interaction and should be kept in mind if the document contains other form elements. \end{itemize} @@ -61,9 +86,9 @@ This section describes some libraries which come with \PGFPlots, but they are mo \begin{itemize} \item I have used a javascript |sprintf| implementation of Kevin van Zonneveld~\cite{phptojs} (the javascript API has only a limited set of conversions). \end{itemize} -\end{tikzlibrary} +\end{pgfplotslibrary} -It is possible to customize |pgfplotsclickable| with several options. +It is possible to customize |pgfplots.clickable| with several options. \begin{pgfplotskey}{clickable=\mchoice{true,false} (initially true)} Allows to disable the library for single plots. @@ -176,3 +201,16 @@ This library provides essentially one command, |\pgfplotsclickablecreate| which \begin{pgfplotskeylist}{annot/xmin=\marg{number},annot/xmax=\marg{number},annot/ymin=\marg{number},annot/ymax=\marg{number} (initially empty)} These required keys communicate the axis limits to |\pgfplotsclickablecreate|. They should be set to numbers which can be assigned to a javascript floating point number (standard IEEE double precision). \end{pgfplotskeylist} + +\input pgfplots.libs.units.tex +\input pgfplots.libs.groupplot.tex + +\subsection{Image Externalization} +\begin{pgfplotslibrary}{external} + The |external| library offers a convenient method to export every single |tikzpicture| into a separate~|.pdf| (or~|.eps|). Later runs of \LaTeX\ will simply include these graphics, thereby reducing typesetting time considerably. + + This library is documented in more detail in section~\ref{sec:pgfplots:export} ``Export to {\pdf/\eps}''. + + + The |external| library has been written by Christian Feuers\"anger (author of \PGFPlots). It has been contributed to \Tikz\ as general purpose library, so the reference documentation along with all tweaks can be found in~\cite[Section ``Externalization Library'']{tikz}. The command |\usepgfplotslibrary{external}| is actually just a wrapper which loads |\usetikzlibrary{external}| or, if this library does not yet exist because the installed \pgfname\ has at most version $2.00$, it will load a copy which is shipped with \PGFPlots. +\end{pgfplotslibrary} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.units.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.units.tex new file mode 100644 index 00000000000..7d217a22b3a --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.units.tex @@ -0,0 +1,176 @@ +\subsection{Units in Labels} +\label{sec:units} + +{\noindent {\emph{by Nick Papior Andersen}}} + +\begin{pgfplotslibrary}{units} + A library which allows to use automatic typesetting of units in labels. The library utilizes different keys to typeset the final output in a consistent way. + Calling one of the commands automatically sets the key `|use units=true|' so one has not to worry of this. +\end{pgfplotslibrary} +\PGFPlots\ has the capability of supporting units. This provides quick customization of the plot as well as the addition of units in labels. + +Loading the library automatically enables the typesetting of units in labels. Currently it only supports predefined SI units but a per-user customization is also +implemented such that it can be used in any way you like. + +First the key which enables you to switch on/off the unit system. +\begin{pgfplotskey}{use units=\marg{boolean} (initially true)} + This key simply enables \PGFPlots\ to use what is described next. This key will be set to true if you load the library. You can use this to temporarily + determine whether the unit library should be used in plots. +\end{pgfplotskey} +\begin{pgfplotsxykey}{\x\ unit=\marg{unit} (initially empty)} + These keys sets the unit in their respective axis. In SI units you could for instance set the |x unit| in Newton as |x unit=N|. +\end{pgfplotsxykey} +\begin{pgfplotsxykey}{\x\ unit prefix=\marg{prefix} (initially empty)} + These keys sets the prefix of the unit. If a value on the |y axis| is in kilo you would set the |y unit prefix=k|. Prefix will be typeset in front of the unit. + + This command will not intervene with the basis of the axis system. I.e. a prefix as just mentioned will not divide every |y axis| number by 1000. + In order to do this see key \meta{axis}| SI prefix|, see Section \ref{sec:SI:prefix}. + + Notice that if the \meta{axis}| unit| isn't set the entire unit will not be typeset. + + \paragraph{Remarks:} Remember that all typesetting of labels occur within a \$\$ environment. Therefore one can use \textbackslash|frac| + and other mathematics commands. +\end{pgfplotsxykey} +Often one just have to utilize the above mentioned keys. It is the basis of the unit typesetting system provided by \PGFPlots. +% \usepgfplotslibrary{units} +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[use units, + x unit=m,x unit prefix=k, + y unit=N,y unit prefix=m, + xlabel=Distance,ylabel=Force] + \addplot coordinates { + (1,2.3) + (2,2.7) + (3,2.1) + (4,1.8) + (5,1.5) + (6,1.1) + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +Below is an example of what would be yielded according to the styles +\begin{codeexample}[code only] +% x label becomes ``Temperature [T]'', y label becomes ``Nothing'' +\pgfplotsset{use units,x unit=T,xlabel=Temperature,ylabel=Nothing} +% x label becomes ``Temperature'', y label becomes ``Nothing'' +\pgfplotsset{use units,x unit prefix=m,xlabel=Temperature,ylabel=Nothing} +\end{codeexample} +Notice the second example. Only setting the prefix will not activate the unit typesetting. Therefore one should ensure to use the |x unit| key if the +typesetting of the labels should be done. + +For typesetting the units one can also change the appearance. For instance one might not like the square brackets which surround the unit. These can +luckily be changed using the below keys. +\begin{pgfplotskeylist}{unit marking pre=\marg{pre} (initially \textbackslash left[),unit marking post=\marg{post} (initially \textbackslash right]),unit markings=\mchoice{parenthesis,square brackets,slash space} (initially square brackets)} + These keys sets the surroundings of the unit. The initial yields $\left[\frac{1}{2}\right]$ such that you can typeset fractions in units. Be aware that + you can only obtain large fractions if you use \textbackslash|dfrac|. These can easily be set using the option key |unit markings| where the options typesets as the following +\begin{codeexample}[code only] +\pgfplotsset{x unit=T,unit markings=parenthesis} % x unit becomes `` \left(T\right)'' +\pgfplotsset{x unit=T,unit markings=square brackets} % x unit becomes `` \left[T\right]'' +\pgfplotsset{x unit=T,unit markings=slash space} % x unit becomes `` / T'' +\end{codeexample} + Notice that all typesetting of units first inserts a space and then the |unit marking pre| code. + + Of course you can just manually set each of them with the |unit marking pre| and |unit marking post| keys. Just remember that they are typeset within a \$\$. +\end{pgfplotskeylist} + +One will typically typeset the unit with a specific font. To do so an option of changing the typesetting command is supplied. +\begin{pgfplotscodetwokey}{unit code}%\textbackslash mathrm\{\})} + This can be utilized to great extend. As a default the typesetting of the units is as |\mathrm{|\meta{unit prefix}\meta{unit}|}|. But if one for instance + wishes to utilize the package |siunitx|, which has great capabilities in typesetting both units, numbers and angles, one can just set the key as +\begin{codeexample}[code only] +\pgfplotsset{unit code/.code 2 args={\si{#1#2}}} +\end{codeexample} + which would yield the unit as |\si{|\meta{unit prefix}\meta{unit}|}|. + + The first argument is typeset as \meta{unit prefix} and the second argument is \meta{unit}. + + The most important thing is that the command needs exactly two arguments. So if you would like a command that typesets the prefix in bold face and the + unit in normal roman font you should call +\begin{codeexample}[code only] +\pgfplotsset{unit code/.code 2 args={\mathbf{#1}\mathrm{#2}} +\end{codeexample} +\end{pgfplotscodetwokey} + + +\subsubsection{Preset SI prefixes} +\label{sec:SI:prefix} +\index{prefixes!unit} +To support the SI system a number of preset keys are defined. This should yield a more intuitive way of supplying the prefix as well as add some more +functionality. For instance it provides an easy scaling mechanism. +\begin{pgfplotsxykeylist}{\x\ SI prefix=\mchoice{yocto,\dots,milli,centi,deci,deca,hecto,kilo,\dots,yotta} (initially none), + change \x\ base=\mchoice{true,false} (initially false)} + These keys sets the prefix of the unit. The allowed prefixes are: + + \begin{center} + \begin{tabular}{>{\ttfamily}c>{$}c<{$}} + \toprule + \rm Prefix & $Power$\\ + \midrule + yocto & -24\\ + zepto & -21\\ + atto & -18\\ + femto & -15\\ + pico & -12\\ + nano& -9\\ + micro & -6\\ + milli & -3\\ + centi& -2\\ + deci& -1\\ + \bottomrule + \end{tabular}\qquad\qquad + \begin{tabular}{>{\ttfamily}cc} + \toprule + \rm Prefix & Power\\ + \midrule + deca & 1\\ + hecto & 2\\ + kilo & 3\\ + mega & 6\\ + giga & 9\\ + tera& 12\\ + peta & 15\\ + exa & 18\\ + zetta& 21\\ + yotta& 24\\ + \bottomrule + \end{tabular} + \end{center} + + As well as resetting the base of the axis if the key |change |\meta{axis}| base=true|. Just \textbf{remember} to + set the |change |\meta{axis}| base| before using the \meta{axis}| SI prefix| key. + + See the utilization as in the example below. +% \usepgfplotslibrary{units} +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[change x base, + x SI prefix=kilo,x unit=m, + y SI prefix=milli,y unit=N, + xlabel=Distance,ylabel=Force] + \addplot coordinates { + (1000,1) + (2000,1.1) + (3000,1.2) + (4000,1.3) + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + Notice that the |x axis| has changed base without displaying the $\cdot 10^{3}$. This is done by using the key |change x base|. Even though you have used + the key |y SI prefix=milli| the base isn't changed on the |y axis|. Try adding |change y base| just after |change x base| and see the result! +\end{pgfplotsxykeylist} + +The above keys are the easy implementation of the base change. Below is a further customization of the base change. It makes it easy to implement a prefix +with a custom base change. + +\begin{pgfplotskey}{axis base prefix={axis \marg{axis} base \marg{base} prefix \marg{prefix}} (initially empty)} + One can utilize this key to customize further of the base and setting the prefix. +\begin{codeexample}[code only] +\pgfplotsset{change x base,axis base prefix={axis x base -3 prefix k}} +\pgfplotsset{change x base,x SI prefix=kilo} +\end{codeexample} + The above two commands are thus equivalent. Remember that the base should operate in opposite of prefix! +\end{pgfplotskey} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile new file mode 100644 index 00000000000..2ff065a1d46 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.makefile @@ -0,0 +1,147 @@ +ALL_FIGURE_NAMES=$(shell cat pgfplots.figlist) +ALL_FIGURES=$(ALL_FIGURE_NAMES:%=%.pdf) + +allimages: $(ALL_FIGURES) + @echo All images exist now. Use make -B to re-generate them. + +figures/expensiveexamplepgfplots-figure0.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure0" "pgfplots" + +figures/expensiveexamplepgfplots-figure1.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure1" "pgfplots" + +figures/expensiveexamplepgfplots-figure2.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure2" "pgfplots" + +figures/expensiveexamplepgfplots-figure3.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure3" "pgfplots" + +figures/expensiveexamplepgfplots-figure4.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure4" "pgfplots" + +figures/expensiveexamplepgfplots-figure5.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure5" "pgfplots" + +figures/expensiveexamplepgfplots-figure6.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure6" "pgfplots" + +figures/expensiveexamplepgfplots-figure7.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure7" "pgfplots" + +figures/expensiveexamplepgfplots-figure8.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure8" "pgfplots" + +figures/expensiveexamplepgfplots-figure9.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure9" "pgfplots" + +figures/expensiveexamplepgfplots-figure10.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure10" "pgfplots" + +figures/expensiveexamplepgfplots-figure11.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure11" "pgfplots" + +figures/expensiveexamplepgfplots-figure12.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure12" "pgfplots" + +figures/expensiveexamplepgfplots-figure13.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure13" "pgfplots" + +figures/expensiveexamplepgfplots-figure14.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure14" "pgfplots" + +figures/expensiveexamplepgfplots-figure15.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure15" "pgfplots" + +figures/expensiveexamplepgfplots-figure16.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure16" "pgfplots" + +figures/expensiveexamplepgfplots-figure17.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure17" "pgfplots" + +figures/expensiveexamplepgfplots-figure18.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure18" "pgfplots" + +figures/expensiveexamplepgfplots-figure19.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure19" "pgfplots" + +figures/expensiveexamplepgfplots-figure20.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure20" "pgfplots" + +figures/expensiveexamplepgfplots-figure21.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure21" "pgfplots" + +figures/expensiveexamplepgfplots-figure22.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure22" "pgfplots" + +figures/expensiveexamplepgfplots-figure23.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure23" "pgfplots" + +figures/expensiveexamplepgfplots-figure24.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure24" "pgfplots" + +figures/expensiveexamplepgfplots-figure25.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure25" "pgfplots" + +figures/expensiveexamplepgfplots-figure26.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure26" "pgfplots" + +figures/expensiveexamplepgfplots-figure27.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure27" "pgfplots" + +figures/expensiveexamplepgfplots-figure28.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure28" "pgfplots" + +figures/expensiveexamplepgfplots-figure29.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure29" "pgfplots" + +figures/expensiveexamplepgfplots-figure30.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure30" "pgfplots" + +figures/expensiveexamplepgfplots-figure31.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure31" "pgfplots" + +figures/expensiveexamplepgfplots-figure32.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure32" "pgfplots" + +figures/expensiveexamplepgfplots-figure33.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure33" "pgfplots" + +figures/expensiveexamplepgfplots-figure34.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure34" "pgfplots" + +figures/expensiveexamplepgfplots-figure35.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure35" "pgfplots" + +figures/expensiveexamplepgfplots-figure36.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure36" "pgfplots" + +figures/expensiveexamplepgfplots-figure37.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure37" "pgfplots" + +figures/expensiveexamplepgfplots-figure38.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure38" "pgfplots" + +figures/expensiveexamplepgfplots-figure39.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure39" "pgfplots" + +figures/expensiveexamplepgfplots-figure40.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure40" "pgfplots" + +figures/expensiveexamplepgfplots-figure41.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure41" "pgfplots" + +figures/expensiveexamplepgfplots-figure42.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure42" "pgfplots" + +figures/expensiveexamplepgfplots-figure43.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure43" "pgfplots" + +figures/expensiveexamplepgfplots-figure44.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure44" "pgfplots" + +figures/expensiveexamplepgfplots-figure45.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure45" "pgfplots" + +figures/expensiveexamplepgfplots-figure46.pdf: + pdflatex -shell-escape -halt-on-error -interaction=batchmode -jobname "figures/expensiveexamplepgfplots-figure46" "pgfplots" + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf Binary files differindex ce2c25e57dd..170ab6b8f99 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.pdf diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex index bda771de8ad..89d61c21c26 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.preamble.tex @@ -19,6 +19,8 @@ % % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\pdfminorversion=5 % to allow compression +\pdfobjcompresslevel=2 \documentclass[a4paper]{ltxdoc} \usepackage{makeidx} @@ -30,12 +32,22 @@ \makeatother \usepackage{ifpdf} -\ifpdf - \usepackage[pdftex]{hyperref} -\else - \usepackage[dvipdfm]{hyperref} -\fi -\hypersetup{pdfborder={0 0 0}} +\usepackage[pdfborder=0 0 0]{hyperref} + \hypersetup{% + colorlinks=true, % use true to enable colors below: + linkcolor=blue,%red, + filecolor=blue,%magenta, + pagecolor=blue,%red, + urlcolor=blue,%cyan, + citecolor=blue, + %frenchlinks=false, % small caps instead of colors + pdfborder=0 0 0, % PDF link-darstellung, falls colorlinks=false. 0 0 0: nix. 0 0 1: default. + %plainpages=false, % Das ist notwendig, wenn die Seitenzahlen z.T. in Arabischen und z.T. in römischen Ziffern gemacht werden. + pdftitle=Package PGFPLOTS manual, + pdfauthor=Christian Feuersänger, + %pdfsubject=, + pdfkeywords={pgfplots pgf tikz tex latex}, + } \makeatletter \let\@wrindex=\@old@wrindex @@ -76,13 +88,17 @@ } \else - \def\pgfsysdriver{pgfsys-dvipdfm.def} +% \def\pgfsysdriver{pgfsys-dvipdfm.def} \fi %\def\pgfsysdriver{pgfsys-pdftex.def} \usepackage{pgfplots} \ifpdf - \usetikzlibrary{pgfplotsclickable} + % this allows to disable the clickable lib from command line using + % \pdflatex '\def\pgfplotsclickabledisabled{1}\input{pgfplots.tex}' + \expandafter\ifx\csname pgfplotsclickabledisabled\endcsname\relax + \usepgfplotslibrary{clickable} + \fi \fi %\usepackage{fp} @@ -90,7 +106,7 @@ % this requires pgf version NEWER than 2.00 : %\usetikzlibrary{fixedpointarithmetic} -\usetikzlibrary{dateplot} +\usepgfplotslibrary{dateplot,units,groupplots} \usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry} \usepackage{amsmath,amssymb} @@ -103,17 +119,44 @@ \graphicspath{{figures/}} +\def\preambleconfig{width=7cm,compat=newest} + + +\expandafter\pgfplotsset\expandafter{\preambleconfig} + + +\makeatletter +% And now, invoke +% /codeexample/typeset listing/.add={% Preamble:\pgfplotsset{\preambleconfig}}{}} +% since listings are VERBATIM, I need to do some low-level things +% here to get the correct \catcodes: +\pgfkeys{/codeexample/typeset listing/.add code={% + \ifcode@execute + \pgfutil@in@{axis}{#1}% + \ifpgfutil@in@ + {\tiny + \% Preamble: \pgfmanualpdfref{\textbackslash pgfplotsset}{\pgfmanual@pretty@backslash pgfplotsset}% + \pgfmanual@pretty@lbrace \expandafter\pgfmanualprettyprintpgfkeys\expandafter{\preambleconfig}\pgfmanual@pretty@rbrace + }% + \fi + \fi + }{},% + %/codeexample/typeset listing/.show code, +}% +\makeatother + +\pgfplotsset{ + %every axis/.append style={width=7cm}, + filter discard warning=false, +} + \pgfqkeys{/codeexample}{% - every codeexample/.style={ + every codeexample/.append style={ width=8cm, /pgfplots/every axis/.append style={legend style={fill=graphicbackground}} }, tabsize=4, } -\pgfplotsset{ - every axis/.append style={width=7cm}, - filter discard warning=false, -} \usetikzlibrary{backgrounds,patterns} % Global styles: @@ -134,9 +177,8 @@ \newcommand\Tikz{Ti\textit kZ} \newcommand\PGF{\textsc{pgf}} -\newcommand\PGFPlots{\textsc{pgfplots}} -\def\PGFPlotstable{\textsc{PgfplotsTable}} - +\newcommand\PGFPlots{\pgfplotsmakefilelinkifuseful{pgfplots}{\textsc{pgfplots}}} +\newcommand\PGFPlotstable{\pgfplotsmakefilelinkifuseful{pgfplotstable}{\textsc{PgfplotsTable}}} \makeindex diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex new file mode 100644 index 00000000000..7999d661e5b --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.2dplots.tex @@ -0,0 +1,1117 @@ + +\subsection{Two Dimensional Plot Types} +\PGFPlots\ supports several two-dimensional line-plots like piecewise linear line plots, piecewise constant plots, smoothed plots, bar plots and comb plots. Most of them use the \PGF\ plot handler library directly, see \cite[section 18.8]{tikz}. + +Plot types are part of the plot style, so they are set with options. Most of the basic 2d plot types are part of \Tikz, see \cite[section 18.8]{tikz}, and are probably known to users of \Tikz. They are documented here as well. + + +\subsubsection{Linear Plots} +\begin{plottype}{sharp plot} +Linear (`sharp') plots are the default. Point coordinates are simply connected by straight lines. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \addplot+[sharp plot] coordinates + {(0,0) (1,2) (2,3)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +The `|+|' here means to use the normal plot cycle list and append `|sharp plot|' to its option list. +\end{plottype} + +\subsubsection{Smooth Plots} +\begin{plottype}{smooth} +Smooth plots interpolate smoothly between successive points. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \addplot+[smooth] coordinates + {(0,0) (1,2) (2,3)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +\subsubsection{Constant Plots} +Constant plots draw lines parallel to the $x$-axis to connect coordinates. The discontinuos edges may be drawn or not, and marks may be placed on left or right ends. + +\begin{plottype}{const plot} +Connects all points with horizontal and vertical lines. Marks are placed left-handed on horizontal line segments, causing the plot to be right-sided continuous at all data points. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[const plot] +coordinates +{(0,0.1) (0.1,0.15) (0.2,0.5) (0.3,0.62) + (0.4,0.56) (0.5,0.58) (0.6,0.65) (0.7,0.6) + (0.8,0.58) (0.9,0.55) (1,0.52)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ymin=0,ymax=1,enlargelimits=false] +\addplot + [const plot,fill=blue,draw=black] +coordinates +{(0,0.1) (0.1,0.15) (0.2,0.5) (0.3,0.62) + (0.4,0.56) (0.5,0.58) (0.6,0.65) (0.7,0.6) + (0.8,0.58) (0.9,0.55) (1,0.52)} + \closedcycle; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +\begin{plottype}{const plot mark left} +An alias for `|const plot|'. +\end{plottype} + +\begin{plottype}{const plot mark right} + A variant which places marks on the right of each line segment, causing plots to be left-sided continuous at coordinates. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[const plot mark right] +coordinates +{(0,0.1) (0.1,0.15) (0.2,0.5) (0.3,0.62) + (0.4,0.56) (0.5,0.58) (0.6,0.65) (0.7,0.6) + (0.8,0.58) (0.9,0.55) (1,0.52)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +\begin{plottype}{jump mark left} +A variant of `|const plot mark left|' which does not draw vertical lines. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[samples=8] +\addplot+[jump mark left,domain=-5:0] + {4*x^2 - 5}; + +\addplot+[jump mark right,domain=-5:0] + {0.7*x^3 + 50}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +\begin{plottype}{jump mark right} +A variant of `|const plot mark right|' which does not draw vertical lines. +\end{plottype} + +\subsubsection{Bar Plots} +Bar plots place horizontal or vertical bars at coordinates. Multiple bar plots in one axis can be stacked on top of each other or aligned next to each other. + +\begin{plottype}{xbar} + Places horizontal bars between the $(y=0)$ line and each coordinate. + + This option is used on a per-plot basis and configures only the visualization of coordinates. The figure-wide style |/pgfplots/xbar| also sets reasonable options for ticks, legends and multiple plots. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[xbar] coordinates + {(4,0) (1,1) (2,2) + (5,3) (6,4) (1,5)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + Bars are centered at plot coordinates with width |bar width|. Using bar plots usually means more than just a different way of how to connect coordinates, for example to draw ticks outside of the axis, change the legend's appearance or introduce shifts if multiple |\addplot| commands appear. + + There is a preconfigured style for |xbar| which is installed automatically if you provide |xbar| as argument to the axis environment which provides this functionality. +% \usetikzlibrary{patterns} +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[xbar,enlargelimits=0.15] +\addplot +[draw=blue,pattern=horizontal lines light blue] +coordinates + {(10,5) (15,10) (5,15) (24,20) (30,25)}; + +\addplot +[draw=black,pattern=horizontal lines dark blue] +coordinates + {(3,5) (5,10) (15,15) (20,20) (35,25)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +Here |xbar| yields |/pgfplots/xbar| because it is an argument to the axis, not to a single plot. + + Besides line-, fill- and colorstyles, bars can be configured with |bar width| and |bar shift|, see below. +\end{plottype} + +\begin{stylekey}{/pgfplots/xbar=\marg{shift for multiple plots} (default 2pt)} + This style sets |/tikz/xbar| \emph{and} some commonly used options concerning horizontal bars for the complete axis. This is automatically done if you provide |xbar| as argument to an axis argument, see above. + +The |xbar| style defines shifts if multiple plots are placed into one axis. It draws bars adjacent to each other, separated by \marg{shift for multiple plots}. Furthermore, it sets the style |bar cycle list| and sets tick and legend appearance options. + +The style is defined as follows. +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/xbar/.style={ + /tikz/xbar, + bar cycle list, + tick align=outside, + xbar legend, + /pgf/bar shift={% + % total width = n*w + (n-1)*skip + % i.e. subtract half for centering + -0.5*(\numplots*\pgfplotbarwidth + (\numplots-1)*#1) + + % the '0.5*w' is for centering + (.5+\plotnum)*\pgfplotbarwidth + \plotnum*#1% + }, + }, +} +\end{codeexample} +The formular for |bar shift| assigns shifts dependent on the total number of plots and the current plot's number. It is designed to fill a total width of $n \cdot $|bar width|$ + (n-1) \cdot $\marg{shift for multiple plots}. The $0.5$ compensates for centering. +\end{stylekey} + +\begin{plottype}{ybar} + Like |xbar|, this option generates bar plots. It draws vertical bars between the ($x=0$) line and each input coordinate. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[ybar] plot coordinates + {(0,3) (1,2) (2,4) (3,1) (4,2)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + The example above simply changes how input coordinates shall be visualized. As mentioned for |xbar|, one usually needs modified legends and shifts for multiple bars in the same axis. + + There is a predefined style which installs these customizations when provided to the axis-environment: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + x tick label style={ + /pgf/number format/1000 sep=}, + ylabel=Population, + enlargelimits=0.15, + legend style={at={(0.5,-0.15)}, + anchor=north,legend columns=-1}, + ybar, + bar width=7pt, +] +\addplot + coordinates {(1930,50e6) (1940,33e6) + (1950,40e6) (1960,50e6) (1970,70e6)}; + +\addplot + coordinates {(1930,38e6) (1940,42e6) + (1950,43e6) (1960,45e6) (1970,65e6)}; + +\addplot + coordinates {(1930,15e6) (1940,12e6) + (1950,13e6) (1960,25e6) (1970,35e6)}; +\legend{Far,Near,Here} +\end{axis} +\end{tikzpicture} +\end{codeexample} +Here |ybar| yields |/pgfplots/ybar| because it is an argument to the axis, not to a single plot. + + 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. + + Sometimes it is useful to write the $y$ values directly near the bars. This can be realized using the |nodes near coords| method: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + x tick label style={ + /pgf/number format/1000 sep=}, + ylabel=Population, + enlargelimits=0.15, + legend style={at={(0.5,-0.15)}, + anchor=north,legend columns=-1}, + ybar=5pt,% configures `bar shift' + bar width=9pt, + nodes near coords, + point meta=y *10^-7 % the displayed number +] +\addplot + coordinates {(1930,50e6) (1940,33e6) + (1950,40e6) (1960,50e6) (1970,70e6)}; + +\addplot + coordinates {(1930,38e6) (1940,42e6) + (1950,43e6) (1960,45e6) (1970,65e6)}; + +\legend{Far,Near} +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +\begin{stylekey}{/pgfplots/ybar=\marg{shift for multiple plots} (default 2pt)} + As |/pgfplots/xbar|, this style sets the |/tikz/ybar| option to draw vertical bars, but it also provides commonly used options for vertical bars. + + If you supply |ybar| to an axis environment, |/pgfplots/ybar| will be chosen instead of |/tikz/ybar|. + + It changes the legend, draws ticks outside of the axis lines and draws multiple |\addplot| arguments adjacent to each other; block--centered at the $x$ coordinate and separated by \marg{shift for multiple plots}. It will also install the |bar shift| for |every node near coord|. Furthermore, it installs the style |bar cycle list|. It is defined similarly to |/pgfplots/xbar|. +\end{stylekey} + +\begin{pgfplotskey}{bar cycle list} + A style which installs cycle lists for multiple bar plots. +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/bar cycle list/.style={/pgfplots/cycle list={% + {blue,fill=blue!30!white,mark=none},% + {red,fill=red!30!white,mark=none},% + {brown!60!black,fill=brown!30!white,mark=none},% + {black,fill=gray,mark=none},% + } + }, +} +\end{codeexample} + +\end{pgfplotskey} + +\begin{key}{/pgf/bar width=\marg{dimension} (initially 10pt)} + Configures the width used by |xbar| and |ybar|. It is accepted to provide mathematical expressions. +\end{key} + +\begin{key}{/pgf/bar shift=\marg{dimension} (initially 0pt)} + Configures a shift for |xbar| and |ybar|. Use |bar shift| together with |bar width| to draw multiple bar plots into the same axis. It is accepted to provide mathematical expressions. +\end{key} + + +\begin{plottype}{ybar interval} + This plot type produces vertical bars with width (and shift) relatively to intervals of coordinates. + + There is one conceptional difference when working with intervals: an interval is defined by \emph{two} coordinates. Since |ybar| has one value for each interval, the $i$th bar is defined by + \begin{enumerate} + \item the $y$ value of the $i$th coordinates, + \item the $x$ value of the $i$th coordinate as left interval boundary, + \item the $x$ value of the $(i+1)$th coordinate as right interval boundary. + \end{enumerate} + Consequently, there is \emph{one coordinate too much}: the last coordinate will \emph{only} be used to determine the interval width; its $y$ value doesn't influence the bar appearance. + + It is installed on a per-plot basis and configures \emph{only} the visualization of coordinates. See the style |/pgfplots/ybar interval| which configures the appearance of the complete figure. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[ybar interval] plot coordinates + {(0,2) (0.1,1) (0.3,0.5) (0.35,4) (0.5,3) + (0.6,2) (0.7,1.5) (1,1.5)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ybar interval, + xtick=data, + xticklabel interval boundaries, + x tick label style= + {rotate=90,anchor=east} + ] +\addplot coordinates + {(0,2) (0.1,1) (0.3,0.5) (0.35,4) (0.5,3) + (0.6,2) (0.7,1.5) (1,1.5)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + x tick label style={ + /pgf/number format/1000 sep=}, + ylabel=Population, + enlargelimits=0.05, + legend style={at={(0.5,-0.15)}, + anchor=north,legend columns=-1}, + ybar interval=0.7, +] +\addplot + coordinates {(1930,50e6) (1940,33e6) + (1950,40e6) (1960,50e6) (1970,70e6)}; + +\addplot + coordinates {(1930,38e6) (1940,42e6) + (1950,43e6) (1960,45e6) (1970,65e6)}; + +\addplot + coordinates {(1930,15e6) (1940,12e6) + (1950,13e6) (1960,25e6) (1970,35e6)}; +\legend{Far,Near,Here} +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +\begin{stylekey}{/pgfplots/ybar interval=\marg{relative width} (default 1)} + A style which is intended to install options for |ybar interval| for a complete figure. This includes tick and legend appearance, management of multiple bar plots in one figure and a more adequate |cycle list| using the style |bar cycle list|. +\end{stylekey} + +\begin{plottype}{xbar interval} + As |ybar interval|, just for horizontal bars. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xmin=0,xmax=53, + ylabel=Age, + xlabel=Quantity, + enlargelimits=false, + ytick=data, + yticklabel interval boundaries, + xbar interval, +] +\addplot + coordinates {(10,5) (10.5,10) (15,13) + (24,18) (50,21) (23,25) (10,30) + (3,50) (3,70)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +\begin{stylekey}{/pgfplots/xbar interval=\marg{relative width} (default 1)} + A style which is intended to install options for |xbar interval| for a complete figure, see the style |/pgfplots/ybar interval| for details. +\end{stylekey} + +\begin{pgfplotsxykey}{\x ticklabel interval boundaries} + These are style keys which set |x tick label as interval| (see page~\pageref{key:pgfplots:ticklabelasinterval} for details) and configure the tick appearance to be \marg{start} -- \marg{end} for each tick interval. +\end{pgfplotsxykey} + +\subsubsection{Comb Plots} +Comb plots are very similar to bar plots except that they employ single horizontal/vertical lines instead of rectangles. + +\begin{plottype}{xcomb} +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[xcomb] coordinates + {(4,0) (1,1) (2,2) + (5,3) (6,4) (1,5)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +\begin{plottype}{ycomb} +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[ycomb] plot coordinates + {(0,3) (1,2) (2,4) (3,1) (4,2)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +\subsubsection{Stacked Plots} +\begin{pgfplotskey}{stack plots=\mchoice{x,y,false} (initially false)} + Allows stacking of plots in either $x$ or $y$ direction. Stacking means to add either $x$- or $y$ coordinates of successive |\addplot| commands on top of each other. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[stack plots=y] + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)}; + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)}; + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +|stack plots| is particularly useful for bar plots. The following examples demonstrate its functionality. Normally, it is advisable to use the styles |ybar stacked| and |xbar stacked| which also set some other options. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[stack plots=y,/tikz/ybar] + \addplot coordinates + {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; + \addplot coordinates + {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; + \addplot coordinates + {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ybar stacked] + \addplot coordinates + {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; + \addplot coordinates + {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; + \addplot coordinates + {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[stack plots=x,/tikz/xbar] + \addplot coordinates + {(1,0) (2,1) (2,2) (3,3)}; + \addplot coordinates + {(1,0) (2,1) (2,2) (3,3)}; + \addplot coordinates + {(1,0) (2,1) (2,2) (3,3)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[] + +\begin{tikzpicture} + \begin{axis}[xbar stacked] + \addplot coordinates + {(1,0) (2,1) (2,2) (3,3)}; + \addplot coordinates + {(1,0) (2,1) (2,2) (3,3)}; + \addplot coordinates + {(1,0) (2,1) (2,2) (3,3)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +The current implementation for |stack plots| does \emph{not} interpolate missing coordinates. That means stacking will fail if the plots have different grids. +\end{pgfplotskey} + +\begin{pgfplotskey}{stack dir=\mchoice{plus,minus} (initially plus)} + Configures the direction of |stack plots|. The value |plus| will add coordinates of successive plots while |minus| subtracts them. +\end{pgfplotskey} + +\begin{pgfplotskey}{reverse stacked plots=\mchoice{true,false} (initially true, default true)} + Configures the sequence in which stacked plots are drawn. This is more or less a technical detail which should not be changed in any normal case. + + The motivation is as follows: suppose multiple |\addplot| commands are stacked on top of each other and they are processed in the order of appearance. Than, the second plot could easily draw its lines (or fill area) on top of the first one - hiding its marker or line completely. Therefor, \PGFPlots\ reverses the sequence of drawing commands. + + This has the side-effect that any normal \Tikz-paths inside of an axis will also be processed in reverse sequence. +\end{pgfplotskey} + +\begin{stylekey}{/pgfplots/xbar stacked=\mchoice{plus,minus} (default plus)} + A figure-wide style which enables stacked horizontal bars (i.e.\ |xbar| and |stack plots=x|). It also adjusts the legend and tick appearance and assigns a useful |cycle list|. +\end{stylekey} +\begin{stylekey}{/pgfplots/ybar stacked=\mchoice{plus,minus} (default plus)} + A figure-wide style which enables stacked vertical bars (i.e.\ |ybar| and |stack plots=y|). It also adjusts the legend and tick appearance and assigns a useful |cycle list|. +\end{stylekey} + +\begin{stylekey}{/pgfplots/xbar interval stacked=\mchoice{plus,minus} (default plus)} + A style similar to |/pgfplots/xbar stacked| for the interval based bar plot variant. +\end{stylekey} +\begin{stylekey}{/pgfplots/ybar interval stacked=\mchoice{plus,minus} (default plus)} + A style similar to |/pgfplots/ybar stacked| for the interval based bar plot variant. +\end{stylekey} + +\subsubsection{Area Plots} +Area plots are a combination of |\closedcycle| and |stack plots|. They can be combined with any other plot type. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + stack plots=y, + area style, + enlarge x limits=false] + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)} + \closedcycle; + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)} + \closedcycle; + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)} + \closedcycle; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent +Area plots may need modified legends, for example using the |area legend| key. Furthermore, one may want to consider the |axis on top| key such that filled areas do not overlap ticks and grid lines. + +\begin{stylekey}{/pgfplots/area style} + A style which sets +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/area style/.style={% + area cycle list, + area legend, + axis on top, + }} +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/pgfplots/area cycle list} + A style which installs a |cycle list| suitable for area plots. The initial configuration of this style simply invokes the |bar cycle list| which does also provide filled plot styles. +\end{stylekey} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + const plot, + stack plots=y, + area style, + enlarge x limits=false] + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)} + \closedcycle; + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)} + \closedcycle; + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)} + \closedcycle; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + smooth, + stack plots=y, + area style, + enlarge x limits=false] + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)} + \closedcycle; + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)} + \closedcycle; + \addplot coordinates + {(0,1) (1,1) (2,2) (3,2)} + \closedcycle; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\pgfplotstableread{pgfplots.timeseries.dat}\table +\pgfplotstabletypeset\table +\end{codeexample} +\begin{codeexample}[] +\pgfplotstableread + {pgfplots.timeseries.dat} + {\table} + +\begin{tikzpicture} + \begin{axis}[ + ymin=0, + minor tick num=4, + enlarge x limits=false, + axis on top, + every axis plot post/.append style= + {mark=none}, + const plot, + legend style={ + area legend, + at={(0.5,-0.15)}, + anchor=north, + legend columns=-1}] + + \addplot[draw=blue,fill=blue!30!white] + table[x=time,y=1minload] from \table + \closedcycle; + \addplot table[x=time,y=nodes] from \table; + \addplot table[x=time,y=cpus] from \table; + \addplot table[x=time,y=processes] + from \table; + \legend{1min load,nodes,cpus,processes} + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[width=4cm] +\pgfplotstableread{pgfplots.timeseries.dat}\table + +\begin{tikzpicture} + \begin{axis}[ + ymin=0, + minor tick num=4, + enlarge x limits=false, + const plot, + axis on top, + stack plots=y, + cycle list={% + {blue!70!black,fill=blue},% + {blue!60!white,fill=blue!30!white},% + {draw=none,fill={rgb:red,138;green,82;blue,232}},% + {red,thick}% + }, + ylabel={Mem [GB]}, + legend style={ + area legend, + at={(0.5,-0.15)}, + anchor=north, + legend columns=2}] + + \addplot table[x=time,y=memused] from \table \closedcycle; + \addplot table[x=time,y=memcached] from \table \closedcycle; + \addplot table[x=time,y=membuf] from \table \closedcycle; + \addplot+[stack plots=false] + table[x=time,y=memtotal] from \table; + \legend{Memory used,Memory cached,Memory buffered,Total memory} + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\subsubsection{Scatter Plots} +\label{sec:pgfplots:scatter:2d} +The most simple scatter plots produce the same as the line plots above -- but they contain only markers. They are enabled using the |only marks| key of \Tikz. +\begin{plottype}{only marks} +Draws a simple scatter plot: all markers have the same appearance. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[enlargelimits=false] + \addplot+[only marks,samples=400] + {rand}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + The |only marks| visualization style simply draws marks at every coordinate. Marks can be set with |mark=|\meta{mark name} and marker options like size and color can be specified using the |mark options=|\marg{style options} key (or by modifying the |every mark| style). The available markers along with the accepted style options can be found in section~\ref{sec:markers} on page~\pageref{sec:markers}. +\end{plottype} + +\label{pgfplots:scatter} +More sophisticated scatter plots change the marker appearance for each data point. An example is that marker colors depend on the magnitude of function values $f(x)$ or other provided coordinates. The term ``scatter plot'' will be used for this type of plots in the following sections. + +Scatter plots require ``source'' coordinates. These source coordinates can be the $y$ coordinate, or explicitly provided additional values. + +\begin{plottype}[/pgfplots]{scatter} + Enables marker appearance modifications. The default implementation acquires ``source coordinates'' for every data point (see |scatter src| below) and maps them linearly into the current color map. The resulting color is used as draw and fill color of the marker. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot+[scatter,only marks, + samples=50,scatter src=y] + {x-x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The key |scatter| is simply a boolean variable which enables marker modifications. It applies only to markers and it can be combined with any other plot type. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot+[scatter, + samples=50,scatter src=y] + {x^3}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +Scatter plots can be configured using a set of options. One of them is mandatory, the rest allows fine grained control over marker appearance options. + +\begin{pgfplotskey}{scatter src=\mchoice{none,\meta{expression},x,y,z,f(x),explicit,explicit symbolic} (initially none)} +\label{pgfplots:scatter:src} + This key is necessary for any scatter plot and it is set to |f(x)| as soon as |scatter| is activated and no different choice has been made. It needs to be provided as \marg{option} for |\addplot| to configure the value used to determine marker appearances. Actually, |scatter src| is nothing but an alias for |point meta|, so the main documentation for this key is on page~\pageref{pgfplots:pointmeta}. However, we summarize the choices here together with scatter plot examples. + + Usually, |scatter src| provides input data (numeric or string type) which is used to determine colors and other style options for markers. + The default configuration expects numerical data which is mapped linearly into the current color map. + + The value of |scatter src| determines how to get this data: the choices \declaretext{x}, \declaretext{y} and \declaretext{z} will use either the $x$, $y$ or $z$ coordinates to determine marker options. Any coordinate filters, logarithms or stacked-plot computations have already been applied to these values (use |rawx|, |rawy| and |rawz| for unprocessed values). The special choice |f(x)| is the same as |y| for two dimensional plots and the same as |z| for three dimensional plots. The choice \declaretext{explicit} expects the scatter source data as additional coordinate from the coordinate input streams (see section~\ref{pgfplots:providing:input} for how to provide input meta data or below for some small examples). They will be treated as numerical data. The choice \declaretext{explicit symbolic} also expects scatter source data as additional meta information for each input coordinate, but it treats them as strings, not as numerical data. Consequently, no arithmetics is performed. It is task of the scatter plot style to do something with it. See, for example, the |scatter/classes| style below. + Finally, it is possible to provide an arbitrary mathematical expression which involves zero, one or more of the values \declaretext{x} (the current $x$ coordinate), \declaretext{y} (the current $y$ coordinate) or \declaretext{z} (the current $z$ coordinate, if any). + + If data is read from tables, mathematical expressions might also involve |\thisrow|\marg{column name} or |\thisrowno|\marg{column index} to access any of the table cells in the current row. + + Here are examples for how to provide data for the choices \declaretext{explicit} and \declaretext{explicit symbolic}. +\begin{codeexample}[code only] +\begin{tikzpicture} + \begin{axis} + % provide color data explicitly using [<data>] + % behind coordinates: + \addplot+[scatter,scatter src=explicit] + coordinates { + (0,0) [1.0e10] + (1,2) [1.1e10] + (2,3) [1.2e10] + (3,4) [1.3e10] + % ... + }; + + % Assumes a datafile.dat like + % xcolname ycolname colordata + % 0 0 0.001 + % 1 2 0.3 + % 2 2.1 0.4 + % 3 3 0.5 + % ... + % the file may have more columns. + \addplot+[scatter,scatter src=explicit] + table[x=xcolname,y=ycolname,meta=colordata] + {datafile.dat}; + % Same data as last example: + \addplot+[scatter,scatter src=\thisrow{colordata}+\thisrow{ycolname}] + table[x=xcolname,y=ycolname] + {datafile.dat}; + + % Assumes a datafile.dat like + % 0 0 0.001 + % 1 2 0.3 + % 2 2.1 0.4 + % 3 3 0.5 + % ... + % the first three columns will be used here: + \addplot+[scatter,scatter src=explicit] + file {datafile.dat}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Please note that |scatter src|$\neq$|none| results in computational work even if |scatter=false|. +\end{pgfplotskey} + +\begin{stylekey}{/pgfplots/scatter/use mapped color=\marg{options for each marker} (initially draw=mapped color!80!black,fill=mapped color)} + This style is installed by default. When active, it recomputes the color |mapped color| for every processed point coordinate by transforming the |scatter src| coordinates into the current color map linearly. Then, it evaluates the options provided as \marg{options for each marker} which are expected to depend on |mapped color|. + + The user interface for color maps is described in section~\ref{pgfplots:colormap}. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[title=Default arguments] +\addplot+[scatter,scatter src=y] + {2*x+3}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title=Black fill color and varying draw color, + scatter/use mapped color= + {draw=mapped color,fill=black}] +\addplot+[scatter,scatter src=y] + {2*x+3}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title=Black draw color and varying fill color, + scatter/use mapped color= + {draw=black,fill=mapped color}] +\addplot+[scatter,scatter src=y] + {2*x+3}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + This key is actually a style which redefines |@pre marker code| and |@post marker code| (see below). + + \paragraph{Remark:} The style |use mapped color| \emph{re}defines |@pre marker code| and |@post marker code|. There is a starred variant \declareandlabel{use mapped color*} which \emph{appends} the functionality while keeping the old marker code. +\end{stylekey} + +\begin{stylekey}{/pgfplots/scatter/classes=\marg{styles for each classname}} +\label{pgfplots:scatterclasses} + A scatter plot style which visualizes points using several classes. The style assumes that every point coordinate has a class label attached, that means the choice |scatter src=explicit symbolic| is assumed\footnote{If \texttt{scatter src} is not \texttt{explicit symbolic}, we expect a numeric argument which is rounded to the nearest integer. The resulting integer is used a class label. If that fails, the numeric argument is truncated to the nearest integer. If that fails as well, the point has no label.}. A class label can be a number, but it can also be a symbolic constant. Given class labels for every point, \marg{styles for each classname} contains a comma-separated list which associates appearance options to each class label. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[scatter/classes={ + a={mark=square*,blue},% + b={mark=triangle*,red},% + c={mark=o,draw=black}}] + + % \addplot[] is better than \addplot+[] here: + % it avoids scalings of the cycle list + \addplot[scatter,only marks, + scatter src=explicit symbolic] + coordinates { + (0.1,0.15) [a] + (0.45,0.27) [c] + (0.02,0.17) [a] + (0.06,0.1) [a] + (0.9,0.5) [b] + (0.5,0.3) [c] + (0.85,0.52) [b] + (0.12,0.05) [a] + (0.73,0.45) [b] + (0.53,0.25) [c] + (0.76,0.5) [b] + (0.55,0.32) [c] + }; +\end{axis} +\end{tikzpicture} +\end{codeexample} +In this example, the coordinate |(0.1,0.15)| has the associated label `|a|' while |(0.45,0.27)| has the label `|c|' (see section~\ref{sec:addplot} for details about specifying point meta data). Now, The argument to |scatter/classes| contains styles for every label -- for label `|a|', square markers will be drawn in color blue. + +The generation of a legend works as for a normal plot -- but |scatter/classes| requires one legend entry for every provided class. It communicates the class labels to the legend automatically. It works as if there had been different |\addplot| commands, one for every class label. + +It is also possible to provide |scatter/classes| as argument to a single plot, allowing different scatter plots in one axis. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[legend pos=south east] + % The data file contains: + % x y label + % 0.1 0.15 a + % 0.45 0.27 c + % 0.02 0.17 a + % 0.06 0.1 a + % 0.9 0.5 b + % 0.5 0.3 c + % 0.85 0.52 b + % 0.12 0.05 a + % 0.73 0.45 b + % 0.53 0.25 c + % 0.76 0.5 b + % 0.55 0.32 c + \addplot[ + scatter/classes={ + a={mark=square*,blue},% + b={mark=triangle*,red},% + c={mark=o,draw=black,fill=black}% + }, + scatter,only marks, + scatter src=explicit symbolic] + table[x=x,y=y,meta=label] + {plotdata/scattercl.dat}; + + \addplot coordinates + {(0.1,0.1) (0.5,0.3) (0.85,0.5)}; + \legend{Class 1,Class 2,Class 3,Line} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +In general, the format of \marg{styles for each classname} is a comma separated list of \meta{label}|=|\marg{style options}. + +\paragraph{Attention:} The keys |every mark| and |mark options| have \emph{no effect} when used inside of \marg{styles for each classname}! So, instead of assigning |mark options|, you can simply provide the options directly. They apply only to markers anyway. + +\paragraph{Remark:} To use |\label| and |\ref| in conjunction with |scatter/classes|, you can provide the class labels as optional arguments to |\label| in square brackets: + +\begin{codeexample}[code only] +\addplot[ + scatter/classes={ + a={mark=square*,blue},% + b={mark=triangle*,red},% + c={mark=o,draw=black,fill=black}% + }, + scatter,only marks, + scatter src=explicit symbolic] + % [and coordinate input here... ] + ; + +\label[a]{label:for:first:class} +\label[b]{label:for:second:class} +\label[c]{label:for:third:class} + +... +First class is \ref{label:for:first:class}, second is \ref{label:for:second:class}. +\end{codeexample} + + \paragraph{Remark:} The style |scatter/classes| \emph{re}defines |@pre marker code| and |@post marker code|. There is a starred variant \declareandlabel{scatter/classes*} which \emph{appends} the functionality while keeping the old marker code. +\end{stylekey} + +\begin{pgfplotskey}{nodes near coords=\marg{content} (default \textbackslash pgfmathprintnumber\textbackslash pgfplotspointmeta)} + A |scatter| plot style which places text nodes near every coordinate. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[nodes near coords] + \addplot+[only marks] coordinates { + (0.5,0.2) (0.2,0.1) (0.7,0.6) + (0.35,0.4) (0.65,0.1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + The \marg{content} is, if nothing else has been specified, the content of the ``point meta'', displayed using the default \meta{content}=|\pgfmathprintnumber{\pgfplotspointmeta}|. The macro |\pgfplotspointmeta| contains whatever has been selected by the |point meta| key, it defaults to the $y$ coordinate for two dimensional plots and the $z$ coordinate for three dimensional plots. + + Since |point meta=explicit symbolic| allows to treat string data, you can provide textual descriptions which will be shown inside of the generated nodes\footnote{In this case, the |\textbackslash pgfmathprintnumber| will be skipped automatically.}: + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[nodes near coords,enlargelimits=0.2] + \addplot+[only marks, + point meta=explicit symbolic] + coordinates { + (0.5,0.2) [(1)] + (0.2,0.1) [(2)] + (0.7,0.6) [(3)] + (0.35,0.4) [(4)] + (0.65,0.1) [(5)] + }; +\end{axis} +\end{tikzpicture} +\end{codeexample} + The square brackets are the way to provide explicit |point meta| for |plot coordinates|. Please refer to the documentation of |plot file| and |plot table| for how to get point meta from files. + + The style |nodes near coords| might be useful for bar plots, see |ybar| for an example of |nodes near coords|. + + \paragraph{Remarks and Details:} + \begin{itemize} + \item |nodes near coords| uses the same options for line styles and colors as the current plot. This may be changed using the style |every node near coord|, see below. + + \item |nodes near coords| is actually one of the |scatter| plot styles. It redefines |scatter/@pre marker code| to generate several \Tikz\ |\node| commands. + + In order to use |nodes near coords| together with other |scatter| plot styles (like |scatter/use mapped color| or |scatter/classes|), you may append a star to each of these keys. The variant \declareandlabel{nodes near coords*} will \emph{append} code to |scatter/@pre marker code| without overwriting the previous value. + \item Consider using |enlargelimits| together with |nodes near coords| if text is clipped away. + \item Currently |nodes near coords| does not work satisfactory for |ybar interval| or |xbar interval|, sorry. + + \end{itemize} +\end{pgfplotskey} + +\begin{stylekey}{/pgfplots/every node near coord} + A style used for every node generated by |nodes near coords|. It is initially empty. +\end{stylekey} + +\begin{pgfplotskey}{nodes near coords align=\marg{alignment method} (initially auto)} + Specifies how to align nodes generated by |nodes near coords|. + + Possible choices for \marg{alignment} are + + \begin{description} + \item[]\declare{auto} Uses |horizontal| if the $x$ coordinates are shown or |vertical| in all other cases. This checks the current value of |point meta|. + \item[]\declare{horizontal} uses |left| if |\pgfplotspointmeta| $<0$ and |right| otherwise. + \item[]\declare{vertical} uses |below| if |\pgfplotspointmeta| $<0$ and |above| otherwise. + \item[] Its also possible to provide any \Tikz\ alignment option such as |anchor=north east|, |below| or something like that. It is also allowed if multiple options are provided. + \end{description} +\end{pgfplotskey} + + +\begin{pgfplotsxycodekeylist}{ + scatter/@pre marker code, + scatter/@post marker code} + These two keys constitute the public interface which determines the marker appearance depending on scatter source coordinates. + + Redefining them allows fine grained control even over marker types, linestyles and colors. + + The scatter plot algorithm works as follows: +\begin{enumerate} +\item The scatter source coordinates form a data stream whose data limits are computed additionally to the axis limits. This step is skipped for |symbolic| meta data. +\item Before any markers are drawn, a linear coordinate transformation from these data limits to the interval $[0.0,1000.0]$ is initialised. +\item Every scatter source coordinate\footnote{During the evaluation, the public macros \texttt{\textbackslash pgfplotspointmeta} and \texttt{\textbackslash pgfplotspointmetarange} indicate the source coordinate and the source coordinate range in the format $a:b$ (for log--axis, they are given in fixed point representation and for linear axes in floating point).} will be transformed linearly and the result is available as macro |\pgfplotspointmetatransformed| $ \in [0.0,1000.0]$. + +The decision is thus based on per thousands of the data range. The transformation is skipped for |symbolic| meta data (and the meta data is simply contained in the mentioned macro). +\item The \pgfname\ coordinate system is translated such that |(0pt,0pt)| is the plot coordinate. +\item The code of |scatter/@pre marker code| is evaluated (without arguments). +\item The standard code which draws markers is evaluated. +\item The code of |scatter/@post marker code| is evaluated (without arguments). +\end{enumerate} + The idea is to generate a set of appearance keys which depends on |\pgfplotspointmetatransformed|. Then, a call to |\scope|\oarg{generated keys} as |@pre| code and the associated |\endscope| as |@post| code will draw markers individually using \oarg{generated keys}. + +A technical example is shown below. It demonstrates how to write user defined routines, in this case a three--class system\footnote{Please note that you don't need to copy this particular example: the multiple--class example is also available as predefined style \texttt{scatter/classes}.}. +\begin{codeexample}[] +\begin{tikzpicture} +% Low-Level scatter plot interface Example: +% use three different marker classes +% 0% - 30% : first class +% 30% - 60% : second class +% 60% - 100% : third class +\begin{axis}[ +scatter/@pre marker code/.code={% + \ifdim\pgfplotspointmetatransformed pt<300pt + \def\markopts{mark=square*,fill=blue}% + \else + \ifdim\pgfplotspointmetatransformed pt<600pt + \def\markopts{mark=triangle*,fill=orange}% + \else + \def\markopts{mark=pentagon*,fill=red}% + \fi + \fi + \expandafter\scope\expandafter[\markopts] +},% +scatter/@post marker code/.code={% + \endscope +}] + +\addplot+[scatter,scatter src=y, + samples=40] + {sin(deg(x))}; + +\end{axis} +\end{tikzpicture} +\end{codeexample} +Please note that |\ifdim| compares \TeX\ lengths, so the example employs the suffix |pt| for any number used in this context. That doesn't change the semantics. The two (!) |\expandafter| constructions make sure that |\scope| is invoked with the \emph{content} of |\markopts| instead of the macro name |\markopts|. +\end{pgfplotsxycodekeylist} + +\subsubsection{1D Colored Mesh Plots} +\begin{plottype}[/pgfplots]{mesh} + Uses the current color map to determine colors for each fixed line segment. Each line segment will get the same color. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot[mesh] {x+sin(deg(x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + The color data is per default the $y$ value of the plot. It can be reconfigured using the |point meta| key (which is actually the same as |scatter src|). The following example provides the color data explicitly for |plot coordinates|, using the square bracket notation. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot[mesh,point meta=explicit] + coordinates { + (0,0) [0] + (1,0.1) [1] + (2,0.1) [2] + (3,0.3) [3] + (4,0.3) [4] + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + This onedimensional |mesh| plot is actually a special case of the twodimensional mesh plots, so more detailed configuration, including how to change the color data, can be found in section~\ref{sec:2d:mesh}. + +\end{plottype} + + +\subsubsection{Interrupted Plots} +\index{Interrupted Plots}% +\label{pgfplots:interrupt}% +Sometimes it is desireable to draw parts of a single plot separately, without connection between the parts (discontinuities). This can be achieved using the |unbounded coords| key combined with coordinate values |nan|, |inf| or |-inf|. + +\begin{pgfplotskey}{unbounded coords=\mchoice{discard,jump} (initially discard)} + This key configures what to do if one or more coordinates of a single point are unbounded. Here, unbounded means it is either $\pm \infty$ (|+inf| or |-inf|) or it has the special ``not--a--number'' value |nan|. + + The initial setting \declaretext{discard} discards the complete point and a warning is issued in the log file\footnote{The warning can be disabled with \texttt{filter discard warning=false}.}. This setting has the same effect as if the unbounded point did not occur: \PGFPlots\ will interpolate between the bounded adjacent points. + + The alternative \declaretext{jump} allows interrupted plots: it provides extra checking for these coordinates and does not interpolate over them; only those line segments which are adjacent to unbounded coordinates will be skipped. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title=Discarding unbounded coords, + unbounded coords=discard] + + \addplot coordinates { + (0,0) (10,50) (20,100) (30,200) + (40,inf) (50,600) (60,800) (80,1000) + }; +\end{axis} +\end{tikzpicture} +\begin{tikzpicture} +\begin{axis}[ + title=Jumps at unbounded coords, + unbounded coords=jump] + \addplot coordinates { + (0,0) (10,50) (20,100) (30,200) + (40,inf) (50,600) (60,800) (80,1000) + }; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + For plot expression and its friends, it is more likely to get very large floating point numbers instead of |inf|. In this case, consider using the |restrict x to domain| key described on page~\pageref{key:restrict:x:to:domain}. + + The |unbounded coords=jump| method does also work for mesh/surface plots: every face adjacent to an unbounded coordinate will be discarded in this case. The following example sets up a (cryptic) coordinate filter which cuts out a quarter of the domain and replaces its values with |nan|: + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + unbounded coords=jump, + % A technical filter to cut out + % the x<0 and y<0 edge. + filter point/.code={% + \pgfmathparse + {\pgfkeysvalueof{/data point/x}<0}% + \ifpgfmathfloatcomparison + \pgfmathparse + {\pgfkeysvalueof{/data point/y}<0}% + \ifpgfmathfloatcomparison + \pgfkeyssetvalue{/data point/x}{nan}% + \fi + \fi + }, + ] + \addplot3[surf] {exp(-sqrt(x^2 + y^2))}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dconfiguration.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dconfiguration.tex new file mode 100644 index 00000000000..4192dae2e56 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dconfiguration.tex @@ -0,0 +1,333 @@ + + +\subsection{3D Axis Configuration} +This section described keys which are used to configure the appearance of three dimensional figures. Some of them apply for twodimensional plots as special case as well, and they will also be discussed in the respective sections of this manual. + +\subsubsection{View Configuration} +\begin{pgfplotskey}{view=\marg{azimuth}\marg{elevation} (initially \{25\}\{30\})} + Changes both view angles of a 3D axis. The azimuth (first argument) is the horizontal angle which is rotated around the $z$ axis. For a 3D plot, the $z$ axis always points to the top. The elevation (second argument) is the vertical rotation around the (rotated) $x$ axis. Positive elevation values indicate a view from above, negative a view from below. All values are measured in degree. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[view={0}{0}, + xlabel=$x$, + zlabel=$z$, + title=View along the positive $y$ axis] + \addplot3[surf] {x}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[view={0}{90}, + xlabel=$x$, + ylabel=$y$, + title=View from top] + \addplot3[surf] {x}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[view={-45}{45}, + xlabel=$x$,ylabel=$y$,zlabel=$z$] + \addplot3[surf] {x}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + +\begin{pgfplotskeylist}{view/az=\marg{azimuth},view/h=\marg{azimuth} (initially 25)} + Changes only the azimuth view angle, i.e.\ the horizontal (first) view angle which is rotated around the~$z$ axis. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[view/h=-30] + \addplot3[ + surf, + %shader=interp, + shader=flat, + samples=50, + domain=-3:3,y domain=-2:2] + {sin(deg(x+y^2))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[view/h=10] + \addplot3[ + surf, + %shader=interp, + shader=flat, + samples=50, + domain=-3:3,y domain=-2:2] + {sin(deg(x+y^2))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[view/h=40,colormap/violet] + \addplot3[ + surf, + %shader=interp, + shader=flat, + samples=50, + domain=-3:3,y domain=-2:2] + {sin(deg(x+y^2))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[view/h=70] + \addplot3[ + surf, + %shader=interp, + shader=flat, + samples=50, + domain=-3:3,y domain=-2:2] + {sin(deg(x+y^2))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskeylist} + +\begin{pgfplotskeylist}{view/el=\marg{elevation},view/v=\marg{elevation} (initially 30)} + Changes only the vertical elevation, i.e.\ the second argument to |view|. Positive values view from above, negative values from below. +\end{pgfplotskeylist} + +\subsubsection{Styles Used Only For 3D Axes} +\begin{stylekey}{/pgfplots/every 3d description} + This style allows to change the appearance of \emph{descriptions} for three dimensional axes. Naturally, a three dimensional axis will display axis labels for $x$ and $y$ differently than a two dimensional axis (for example, the $y$ axis label won't be rotated by 90 degrees). The |every 3d description| style installs the necessary display options for three dimensional axis descriptions. + + The initial value is: +\begin{codeexample}[code only] +\pgfkeys{ + /pgfplots/every 3d description/.style={ + % Only these description styles can be changed here: + every axis x label/.style={at={(ticklabel cs:0.5)}, + anchor=near ticklabel}, + every axis y label/.style={at={(ticklabel cs:0.5)}, + anchor=near ticklabel}, + every x tick scale label/.style={ + at={(xticklabel cs:0.95,5pt)}, + anchor=near xticklabel,inner sep=0pt}, + every y tick scale label/.style={ + at={(yticklabel cs:0.95,5pt)}, + anchor=near yticklabel,inner sep=0pt}, + try min ticks=3, + }% +} +\end{codeexample} + + As the name suggests, |every 3d description| can only be used to set styles for axis labels, tick labels and titles. It has \emph{not} been designed to reset other styles, you will need to change these options either for each axis separately or by means of user defined styles. The reason for this limitation is: other options can (and, in many cases) need to be set before the axis is processed. However, the decision whether we have a two dimensional or a three dimensional axis has to be postponed until the processing is more or less complete -- so only some remaining keys can be set. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every 3d view \marg{h}\marg{v}} + A style which can be used for fine tuning of the output for specific views. + + This style will be installed right after |every 3d description|, but before other axis description related keys are set (in other words: it has higher precedence than |every 3d description| but less precedence than keys provided to the axis directly). + + One example is preconfigured for |view={0}{90}| (from top): +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/every 3d view {0}{90}/.style={ + xlabel near ticks, + ylabel near ticks, + axis on top=true + } +} +\end{codeexample} +\end{stylekey} + + +\subsubsection{Appearance Of The 3D Box} + +\begin{pgfplotskey}{plot box ratio=\marg{x stretch}\marg{y stretch}\marg{z stretch} (initially {1}{1}{1})} + Allows to customize the aspect ratio between the three different axes in a three dimensional plot. + + The |plot box ratio| is applied before any rotations and stretch--to--fill routines have been invoked. Thus, the initial setting |{1}{1}{1}| makes all axes equally long. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + view/h=60, + plot box ratio={1}{1}{1}, + colormap={violet}{[1cm] rgb255(0cm)=(25,25,122) + color(1cm)=(white) rgb255(5cm)=(238,140,238)}, + xlabel=$x$, + ylabel=$t$, + zlabel={$p(x,t)$}, + shader=faceted, + title=Initial \texttt{plot box ratio}, +] + \addplot3[surf,y domain=0.02:3.5,samples=81] + {1/(2*sqrt(pi*y)) * exp(0-x^2/y)}; + % the '0' is a work-around for a bug in PGF 2.00 +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + view/h=60, + plot box ratio={1}{2}{1}, + colormap={violet}{[1cm] rgb255(0cm)=(25,25,122) + color(1cm)=(white) rgb255(5cm)=(238,140,238)}, + xlabel=$x$, + ylabel=$t$, + zlabel={$p(x,t)$}, + shader=flat, + title=\texttt{plot box ratio=1 2 1}, +] + \addplot3[surf,y domain=0.02:3.5,samples=81] + {1/(2*sqrt(pi*y)) * exp(0-x^2/y)}; + % the '0' is a work-around for a bug in PGF 2.00 +\end{axis} +\end{tikzpicture} +\end{codeexample} + + This key applies only to three dimensional axes. After the scaling, the axes will be stretched to fill the |width| and |height| for this plot. Thus, the effects of |plot box ratio| might be undone by this stretching for particular views. +\end{pgfplotskey} + + +\begin{pgfplotskey}{3d box=\mchoice{background,complete,complete*} (initially background)} + \label{pgfplots:key:3dbox} + Allows to configure the appearance of boxed three dimensional axes. + + Type only |3d box| (without value) as alias for |3d box=complete|. + + The choice \declaretext{background} is the initial setting, it does not draw axis lines (and grid lines) which are in the foreground. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + 3d box=background, + % pretty printing, but irrelevant: + title={3d box=background}, + samples=5, + domain=-4:4, + xtick=data, + ytick=data, + ] + \addplot3[surf] {x*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The choice \declaretext{complete} also draws axis lines and tick lines in the foreground, but it doesn't draw grid lines in the foreground. The result yields a complete box: +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + 3d box,% same as 3d box=complete + % pretty printing, but irrelevant: + title={3d box=complete}, + samples=5, + domain=-4:4, + xtick=data, + ytick=data, + ] + \addplot3[surf] {x*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Finally, the choice \declaretext{complete*} is the same as |complete|, but it also draws grid lines. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + 3d box=complete, + grid=major, + title={3d box=complete}, + samples=5, domain=-4:4, + xtick=data, ytick=data, + ] + \addplot3[surf] {x*y}; + \end{axis} +\end{tikzpicture}% +~ +\begin{tikzpicture} + \begin{axis}[ + 3d box=complete*, + grid=major, + title={3d box=complete*}, + samples=5, domain=-4:4, + xtick=data, ytick=data, + ] + \addplot3[surf] {x*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Before any foreground parts are actually processed, the style |every 3d box foreground| will be installed. This allows to change the appearance of foreground axis components like |tick style| or |axis line style| separately from the background components. + + Note that |3d box=complete| is \emph{only} available for boxed axes, i.e.\ together with |axis lines=box|. It is an error to use a different combination. +\end{pgfplotskey} + + + +\subsubsection{Axis Line Variants} +\label{sec:pgfplots:axislines:3d} +Three dimensional axes also benefit from the |axis lines=box| or |axis lines=center| styles discussed in section~\ref{sec:pgfplots:axislines}. The choice |axis lines=box| is standard, it draws a box (probably affected by the |3d box=complete| key). +The choice |axis lines=center| draws all three axes such that they pass through the origin. It might be necessary to combine this key with |axis on top| as there is no depth information. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + axis lines=center, + axis on top, + samples=5, domain=-4:4, + xtick=data, ytick=data, + ztick=\empty, % no z ticks here + ] + \addplot3[surf] {x*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +The remaining choices |axis lines*=left| and |axis lines*=right| select different sets of axes in a way such that tick labels and axis label won't disturb the plot's content. The `|*|' suppress the use of special styles which are mainly adequate for 2d axes, see the documentation of |axis lines|. Such a set of axes is always on the boundary of the two--dimensional projection. + +The choice |axis lines*=left| chooses a set of axes which are left (or bottom, respectively) whereas the choice |axis lines*=right| chooses a set of axes which are on the right (or top, respectively): + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + axis lines*=left, + samples=5, domain=-4:4, + xtick=data, ytick=data, + ] + \addplot3[surf] {x*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + axis lines*=right, + samples=5, domain=-4:4, + xtick=data, ytick=data, + ] + \addplot3[surf] {x*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +It is not (yet) possible to mix different styles like |axis x line=center,axis z line=top|. + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex new file mode 100644 index 00000000000..2140d0d15bf --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex @@ -0,0 +1,719 @@ +\subsection{Three Dimensional Plot Types} +\label{sec:3d} +\PGFPlots\ provides three dimensional visualizations like scatter, line, mesh or surface plots. This section explains the methods to provide input coordinates and how to use the different plot types. + +\subsubsection{Before You Start With 3D} +\label{pgfplots:3d:preliminary} +Before we delve into the capabilities of \PGFPlots\ for three dimensional visualization, let me start with some preliminary remarks. The reason to use \PGFPlots\ for three dimensional plots are similar to those of normal, two dimensional plots: the possibility to get consistent fonts and document consistent styles combined with high--quality output. + +While this works very nice for (not too complex) two dimensional plots, it requires considerably more effort than non--graphical documents. This is even more so for three dimensional plots. In other words: \PGFPlots' three dimensional routines are slow. There are reasons for this and some of them may vanish in future versions. But one of these reasons is, that \TeX\ has never been designed for complex visualisation techniques. Consider the image externalization routines mentioned in section~\ref{sec:pgfplots:export}, in particular the |external| library to reduce typesetting time. Besides the speed limitations, three dimensional plots reach memory limits easily. Therefor, the plot complexity of three dimensional plots is limited to relatively coarse resolutions. Section~\ref{sec:pgfplots:export} also discusses methods to extend the initial \TeX\ memory limits. + +Another issue which arises in three dimensional visualization is depth. \PGFPlots\ supports $z$ buffering techniques up to a certain extend. It works pretty well for single scatter plots (|z buffer=sort|), mesh or surface plots (|z buffer=auto|) or parametric mesh and surface plots (|z buffer=sort|). However, it can't combine different |\addplot| commands, those will be drawn in the order of appearance. +You may encounter the limitations sometimes. Maybe it will be improved in future versions. + +If you decide that you need high complexity, speed and 100\% reliable z buffers (depth information), you should consider using other visualization tools and return to \PGFPlots\ in several years. If you can wait for a complex picture and you don't even see the limitations arising from z buffering limitations, you should use \PGFPlots. Again, consider using the automatic picture externalization with the |external| library discussed in section~\ref{sec:pgfplots:export}. + +Enough for now, let's continue. + +\subsubsection{The \texttt{\textbackslash addplot3} Command: Three Dimensional Coordinate Input} +\label{pgfplots:sec:threedim} +\begin{addplot3generic} + The \verbpdfref{\addplot3} command is the main interface for any three dimensional plot. It works in the same way as its two dimensional variant |\addplot| which has been described in all detail in section~\ref{cmd:pgfplots:addplot} on page~\pageref{cmd:pgfplots:addplot}. + + The \verbpdfref{\addplot3} command accepts the same input methods as the |\addplot| variant, including expression plotting, coordinates, files and tables. However, a third coordinate is necessary for each of these methods which is usually straight--forward and is explained in all detail in the following. + + Furthermore, \verbpdfref{\addplot3} has a way to decide whether a \emph{line} visualization or a \emph{mesh} visualization has to be done. The first one is map from one dimension into $\R^3$ and the latter one a map from two dimensions to $\R^3$. Here, the keys |mesh/rows| and |mesh/cols| are used to define mesh sizes (matrix sizes). Usually, you don't have to care about that because the coordinate input routines already allow either onedimensional or two dimensional structure. +\end{addplot3generic} + +\begin{addplot3operation}[]{coordinates}{\marg{coordinate list}} + The \verbpdfref{\addplot3 coordinates} method works like its twodimensional variant, \verbpdfref{\addplot coordinates} which is described in all detail on page~\pageref{pgfplots:addplot:coordinates}: + + A long list of coordinates |(|\meta{x}|,|\meta{y}|,|\meta{z}|)| is expected, separated by white spaces. The input list can be either an unordered series of coordinates, for example for scatter or line plots. It can also have matrix structure, in which case an empty input line (which is equivalent to ``|\par|'') marks the end of one matrix row. Matrix structure can also be provided if one of |mesh/rows| or |mesh/cols| is provided explicitly. + +\long\def\temporarytest{\noexpand\par} +\begin{codeexample}[newline=\temporarytest] +\begin{tikzpicture} + \begin{axis} + % this yields a 3x4 matrix: + \addplot3[surf] coordinates { + (0,0,0) (1,0,0) (2,0,0) (3,0,0) + + (0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5) + + (0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5) + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + \noindent Here, \verbpdfref{\addplot3} reads a matrix with three rows and four columns. The empty lines separate one row from the following. + + As for the twodimensional |plot coordinates|, it is possible to provide (constant) mathematical expressions inside of single coordinates. The syntax |(|\meta{x}|,|\meta{y}|,|\meta{z}|) |\oarg{meta} can be used just as for two dimensional |plot coordinates| to provide explicit color data; error bars are also supported. +\end{addplot3operation} + +\begin{addplot3operation}[]{file}{\marg{name}} + The \verbpdfref{\addplot3 file} input method is the same as \verbpdfref{\addplot file} -- it only expects one more coordinate. + Thus, the input file contains $x_i$ in the first column, $y_i$ in the second column and $z_i$ in the third. + + A further column is read after $z_i$ if |point meta=explicit| has been requested, see the documentation of \verbpdfref{\addplot file} on page~\pageref{pgfplots:addplot:file} for details. + + As for \verbpdfref{\addplot3 coordinates}, an empty line in the file marks the end of one matrix row. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + % We have `plotdata/first3d.dat' with + %--------- + % 0 0 0.8 + % 1 0 0.56 + % 2 0 0.5 + % 3 0 0.75 + % + % 0 1 0.6 + % 1 1 0.3 + % 2 1 0.21 + % 3 1 0.3 + % + % 0 2 0.68 + % 1 2 0.22 + % 2 2 0.25 + % 3 2 0.4 + % + % 0 3 0.7 + % 1 3 0.5 + % 2 3 0.58 + % 3 3 0.9 + % -> yields a 4x4 matrix: + \addplot3[surf] file {plotdata/first3d.dat}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + For matrix data in files, it is important to specify the ordering in which the matrix entries have been written. The default configuration is |mesh/ordering=x varies|, so you need to change it to |mesh/ordering=y varies| in case you have columnwise ordering. +\end{addplot3operation} + +\begin{addplot3operation}[]{table}{\oarg{column selection}\marg{file}} + The \verbpdfref{\addplot3 table} input works in the same way as its two dimensional counterpart \verbpdfref{\addplot table}. It only expects a column for the $z$ coordinates. Furthermore, it interpretes empty input lines as end--of--row (more generally, end--of--scanline) markers, just as for |plot file|. The remarks above about the |mesh/ordering| applies here as well. +\end{addplot3operation} + +\begin{pgfplotskeylist}{mesh/rows=\marg{integer},mesh/cols=\marg{integer}} + For visualization of mesh or surface plots which need some sort of matrix input, the dimensions of the input matrix need to be known in order to visualize the plots correctly. The matrix structure may be known from end--of--row marks (empty lines as general end--of--scanline markers in the input stream) as has been described above. + + If the matrix structure is not yet known, it is necessary to provide at least one of |mesh/rows| or |mesh/cols| where |mesh/rows| indicates the number of samples for $y$ coordinates whereas |mesh/cols| is the number of samples used for $x$ coordinates (see also |mesh/ordering|). + + Thus, the following example is also a valid method to define an input matrix. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + % this yields also a 3x4 matrix: + \addplot3[surf,mesh/rows=3] coordinates { + (0,0,0) (1,0,0) (2,0,0) (3,0,0) + (0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5) + (0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5) + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + It is enough to supply one of |mesh/rows| or |mesh/cols| -- the missing values will be determined automatically. + + If you provide one of |mesh/rows| or |mesh/cols|, any end--of--row marker seen inside of input files or coordinate streams will be ignored. + +\end{pgfplotskeylist} + +\begin{pgfplotskeylist}{mesh/scanline verbose=\mchoice{true,false} (initially false)} + Provides debug messages in the \LaTeX\ output about end--of--scanline markers. + + The message will tell whether end--of--scanlines have been found and if they are the same. +\end{pgfplotskeylist} + +\begin{pgfplotskey}{mesh/ordering=\mchoice{x varies,y varies,rowwise,colwise} (initially x varies)} + Allows to configure the sequence in which matrizes (meshes) are read from \verbpdfref{\addplot3 coordinates}, \verbpdfref{\addplot3 file} or \verbpdfref{\addplot3 table}. + + Here, \declaretext{x varies} means a sequence of points where $n$=|mesh/cols| successive points have the $y$ coordinate fixed. This is intuitive when you write down a function because $x$ is horizontal and $y$ vertical. Note that in matrix terminology, $x$ refers to \emph{column indices} whereas $y$ refers to \emph{row indices}. Thus, |x varies| is equivalent to \declaretext{rowwise} ordering in this sense. This is the initial configuration. + +\long\def\temporarytest{\noexpand\par} +\begin{codeexample}[newline=\temporarytest] +\begin{tikzpicture} +\begin{axis}[mesh/ordering=x varies] + % this yields a 3x4 matrix in `x varies' + % ordering: + \addplot3[surf] coordinates { + (0,0,0) (1,0,0) (2,0,0) (3,0,0) + + (0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5) + + (0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5) + }; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + Consequently, |mesh/ordering=|\declaretext{y varies} provides points such that successive $m$=|mesh/rows| points form a column, i.e. the $x$ coordinate is fixed and the $y$ coordinate changes. In this sense, |y varies| is equivalent to \declaretext{colwise} ordering, it is actually a matrix transposition. +\long\def\temporarytest{\noexpand\par} +\begin{codeexample}[newline=\temporarytest] +\begin{tikzpicture} +\begin{axis}[mesh/ordering=y varies] + % this yields a 3x4 matrix in colwise ordering: + \addplot3[surf] coordinates { + (0,0,0) (0,1,0) (0,2,0) + + (1,0,0) (1,1,0.6) (1,2,0.7) + + (2,0,0) (2,1,0.7) (2,2,0.8) + + (3,0,0) (3,1,0.5) (3,2,0.5) + }; +\end{axis} +\end{tikzpicture} +\end{codeexample} + Again, note the subtle difference to the common matrix indexing where a column has the second index fixed. \PGFPlots\ refers to the way one would write down a function on a sheet of paper (this is consistent with how Matlab (tm) displays discrete functions with matrizes). + + Please note that |shader=interp| relies on low level shadings which need to be given in row wise ordering, so a (potentially expensive) transposition of the data matrix will be performed in this case. If possible, supply your data in row wise ordering for |shader=interp|. +\end{pgfplotskey} + +\begin{addplot3operation}[]{\marg{math expression}}{} +\label{cmd:addplot3:expr} + \pgfmanualpdflabel{\textbackslash addplot3 expression}{}% + Expression plotting also works in the same way as for two dimensional plots. Now, however, a two dimensional mesh is sampled instead of a single line, which may depend on |x| and |y|. + + The method \verbpdfref{\addplot3} \marg{math expr} visualizes the function $f(x,y) = $\meta{math expr} where $ f \colon [x_1,x_2] \times [y_1,y_2] \to \R$. The interval $[x_1,x_2]$ is determined using the |domain| key, for example using |domain=0:1|. The interval $[y_1,y_2]$ is determined using the |y domain| key. If |y domain| is empty, $[y_1,y_2] = [x_1,x_2]$ will be assumed. If |y domain=0:0| (or any other interval of length zero), it is assumed that the plot does not depend on |y| (thus, it is a line plot). + + The number of samples in $x$ direction is set using the |samples| key. The number of samples in $y$ direction is set using the |samples y| key. If |samples y| is not set, the same value as for $x$ is used. If |samples y|$\le 1$, it is assumed that the plot does not depend on |y| (meaning it is a line plot). + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[surf] {y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colorbar] + \addplot3 + [surf,faceted color=blue, + samples=15, + domain=0:1,y domain=-1:1] + {x^2 - y^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Expression plotting sets |mesh/rows| and |mesh/cols| automatically; these settings don't have any effect for expression plotting. +\end{addplot3operation} + +\begin{addplot3operation}[]{expression}{\marg{math expr}} + The syntax + + \verbpdfref{\addplot3} \marg{math expression}|;| + + as short-hand equivalent for + + \verbpdfref{\addplot3 expression} \marg{math expression}|;| +\end{addplot3operation} + +\begin{addplot3operation}[]{(\meta{$x$ expression},\meta{$y$ expression},\meta{$z$ expression})}{} + A variant of \verbpdfref{\addplot3 expression} which allows to provide different coordinate expressions for the $x$, $y$ and $z$ coordinates. This can be used to generate parameterized plots. + + Please note that |\addplot (x,y,x^2)| is equivalent to |\addplot expression {x^2}|. + + Note further that since the complete point expression is surrounded by round braces, round braces inside of \meta{$x$ expression}, \meta{$y$ expression} or \meta{$z$ expression} need to be treated specially. Surround the expressions (which contain round braces) with curly braces: + + |\addplot3 (|\marg{$x$ expr}|, |\marg{$y$ expr}|, |\marg{$z$ expr}|);| +\end{addplot3operation} + +\subsubsection{Line Plots} + +Three dimensional line plots are generated if the input source has no matrix structure. Line plots take the input coordinates and connect them in the order of appearance. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[xlabel=$x$,ylabel=$y$] + \addplot3 coordinates {(0,0,0) (0,0.5,1) (0,1,0)}; + \addplot3 coordinates {(0,1,0) (0.5,1,1) (1,1,0)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +If there is no value for both, |mesh/rows| and |mesh/cols| or if one of them is |1|, \PGFPlots\ will draw a line plot. This is also the case if there is no end--of--scanline marker (empty line) in the input stream. + +For \verbpdfref{\addplot3 expression}, this requires to set |samples y=0| to disable the generation of a mesh. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[view={60}{30}] +\addplot3+[domain=0:5*pi,samples=60,samples y=0] + ({sin(deg(x))}, + {cos(deg(x))}, + {2*x/(5*pi)}); +\end{axis} +\end{tikzpicture} +\end{codeexample} + +Three dimensional line plots will usually employ lines to connect points (i.e.\ the initial |sharp plot| handler of \Tikz). The |smooth| method of \Tikz\ might also prove be an option. Note that no piecewise constant plot, comb or bar plot handler is supported for three dimensional axes. + +\subsubsection{Scatter Plots} + +Three dimensional scatter plots have the same interface as for two dimensional scatter plots, so all examples of section~\ref{sec:pgfplots:scatter:2d} can be used for the three dimensional case as well. +The key features are to use |only marks| and/or |scatter| as plot styles. + +We provide some more examples which are specific for the three dimensional case. + +Our first example uses |only marks| to place the current plot |mark| at each input position: +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + xlabel=$x$, + ylabel=$y$, + zlabel={$f(x,y) = x\cdot y$}, + title=A Scatter Plot Example] + % `pgfplotsexample4_grid.dat' contains a + % large sequence of input points of the form + % x_0 x_1 f(x) + % 0 0 0 + % 0 0.03125 0 + % 0 0.0625 0 + % 0 0.09375 0 + % 0 0.125 0 + % 0 0.15625 0 + \addplot3+[only marks] table + {plotdata/pgfplotsexample4_grid.dat}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +If we add the key |scatter|, the plot mark will also use the colors of the current |colormap|: +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + xlabel=$x$, + ylabel=$y$, + zlabel={$f(x,y) = x\cdot y$}, + title=A Scatter Plot Example] + \addplot3+[only marks,scatter] table + {plotdata/pgfplotsexample4_grid.dat}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +A more sophisticated example is to draw the approximated function as a |surf| plot (which requires matrix data) and the underlying grid (which is |scatter|ed data) somewhere into the same axis. We choose to place the $(x,y)$ grid points at $z=1.4$. Furthermore, we want the grid points to be colored according to the value of column |f(x)| in the input table: +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + 3d box, + zmax=1.4, + colorbar, + xlabel=$x$, + ylabel=$y$, + zlabel={$f(x,y) = x\cdot y$}, + title={Using Coordinate Filters to fix $z=1.4$}] + % `pgfplotsexample4.dat' contains similar data as in + % `pgfplotsexample4_grid.dat', but it uses a uniform + % matrix structure (same number of points in every scanline). + \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}}] + table {plotdata/pgfplotsexample4_grid.dat}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent We used |z filter| to fix the $z$ coordinate to $1.4$. We could also have used the |table/z expr=1.4| feature +\begin{codeexample}[code only] + \addplot3[scatter,scatter src=\thisrow{f(x)},only marks] + table[z expr=1.4] {plotdata/pgfplotsexample4_grid.dat}; +\end{codeexample} +\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. +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + view={120}{40}, + width=220pt, + height=220pt, + grid=major, + z buffer=sort, + xmin=-1,xmax=9, + ymin=-1,ymax=9, + zmin=-1,zmax=9, + enlargelimits=upper, + xtick={-1,1,...,19}, + ytick={-1,1,...,19}, + ztick={-1,1,...,19}, + xlabel={$l_1$}, + ylabel={$l_2$}, + zlabel={$l_3$}, + point meta={x+y+z+3}, + colormap={summap}{ + color=(black); color=(blue); + color=(black); color=(white) + color=(orange) color=(violet) + color=(red) + }, + scatter/use mapped color={ + draw=mapped color,fill=mapped color!70}, + ] + % `pgfplots_scatter4.dat' contains a large sequence of + % the form + % l_0 l_1 l_2 + % 1 6 -1 + % -1 -1 -1 + % 0 -1 -1 + % -1 0 -1 + % -1 -1 0 + % 1 -1 -1 + % 0 0 -1 + % 0 -1 0 + \addplot3[only marks,scatter,mark=cube*,mark size=7] + table {plotdata/pgfplots_scatterdata4.dat}; + +\end{axis} +\end{tikzpicture} +\end{codeexample} + + +\subsubsection{Mesh Plots} +\label{sec:2d:mesh} +\begin{plottype}[/pgfplots]{mesh} + A mesh plot uses different colors for each mesh segment. Each mesh segment gets the same color. The color is determined using a ``color coordinate'' which is also called ``meta data'' throughout this document. It is the same data which is used for surface and scatter plots as well, see section~\ref{pgfplots:pointmeta}. In the initial configuration, the ``color coordinate'' is the $z$ axis (or the $y$ axis for two dimensional plots). This color coordinate is mapped linearly into the current color map to determine the color for each mesh segment. Thus, if the smallest occuring color data is, say, $-1$ and the largest is $42$, points with color data $-1$ will get the color at the lower end of the color map and points with color data $42$ the color of the upper end of the color map. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[mesh] {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + A mesh plot can be combined with markers or with the |scatter| key which does also draw markers in different colors. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3+[mesh,scatter,samples=10,domain=0:1] + {x*(1-x)*y*(1-y)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[grid=major,view={210}{30}] + \addplot3+[mesh,scatter,samples=10,domain=0:1] + {5*x*sin(2*deg(x)) * y*(1-y)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + \paragraph{Details:} + \begin{itemize} + \item + A mesh plot uses the same implementation as |shader=flat| to get one color for each single segment. Thus, if |shader=flat mean|, the color for a segment is determined using the \emph{mean} of the color data of adjacent vertices. If |shader=flat corner|, the color of a segment is the color of \emph{one} adjacent vertex. + \item As soon as |mesh| is activated, |color=mapped color| is installed. This is \emph{necessary} unless one needs a different color -- but |mapped color| is the only color which reflects the color data. + + It is possible to use a different color using the |color=|\meta{color name} as for any other plot. + + \item It is easily possible to add |mark=|\meta{marker name} to mesh plots, |scatter| is also possible. Scatter plots will use the same color data as for the mesh. + \end{itemize} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[view/az=14] + \addplot3[mesh,draw=red,samples=10] {x^2-y^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Mesh plots use the |mesh legend| style to typeset legend images. +\end{plottype} + +\begin{pgfplotskey}{mesh/check=\mchoice{false,warning,error} (initially error)} + Allows to configure whether an error is generated if |mesh/rows| $\times$ |mesh/cols| does not equal the total number of coordinates. + + If you know exactly what you are doing, it may be useful to disable the check. If you are unsure, it is best to leave the initial setting. +\end{pgfplotskey} + +\begin{pgfplotskey}{z buffer=\mchoice{default,none,auto,sort,reverse x seq,reverse y seq,reverse xy seq} (initially default)} + This key allows to choose between different $z$ buffering strategies. A $z$ buffer determines which parts of an image should be drawn in front of other parts. Since both, the graphics packages \PGF\ and the final document format |.pdf| are inherently two dimensional, this work has to be done in \TeX. Currently, several (fast) heuristics can be used which work reasonably well for simple mesh- and surface plots. Furthermore, there is a (time consuming) sorting method which does also work if the fast heuristics fails. + + The $z$ buffering algorithms of \PGFPlots\ apply only to a single |\addplot| command. Different |\addplot| commands will be drawn on top of each other, in the order of appearance. + + The choice \declaretext{default} checks if we are currently working with a mesh or surface plot and uses |auto| in this case. If not, it sets |z buffer=none|. + + The choice \declaretext{none} disables $z$ buffering. This is also the case for two dimensional axes which don't need $z$ buffering. + + The choice \declaretext{auto} is the initial value for any mesh- or surface plot: it uses a very fast heuristics to decide how to realize $z$ buffering for mesh and surface plots. The idea is to reverse either the sequence of all $x$ coordinates, or those of all $y$ coordinates, or both. For regular meshes, this suffices to provide $z$ buffering. In other words: the choice |auto| will use one of the three reverse strategies |reverse |*| seq| (or none at all). + + The choice \declaretext{sort} can be used for scatter, line, mesh and surface plots. It really sorts according to the depth of each point (or mesh segment)\footnote{The choice \texttt{sort} is \emph{not} available for surface plots with \texttt{shader=interp} because the low level format doesn't support sorting.}. Sorting in \TeX\ uses a slow algorithm and may require a lot of memory (although it has the expected runtime asymptotics $\mathcal O(N \log N)$). + + The remaining choices apply only to mesh/surface plots and do nothing more then their name indicates: they reverse the coordinate sequences (using quasi linear runtime). They should only be used in conjunction by |z buffer=auto|. +\end{pgfplotskey} + +\subsubsection{Surface Plots} +\label{sec:pgfplots:surfplots} +\begin{plottype}[/pgfplots]{surf} + A surface plot visualizes a two dimensional, single patch using different fill colors for each patch segment. Each patch segment is a (pseudo) rectangle, that means input data is given in form of a data matrix as is discussed in the introductory section about three dimensional coordinates,~\ref{pgfplots:sec:threedim}. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[surf,shader=interp] {x*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The simplest way to generate surface plots is to use the plot expression feature, but -- as discussed in section~\ref{pgfplots:sec:threedim} -- other input methods like \verbpdfref{\addplot3 table} or \verbpdfref{\addplot3 coordinates} are also possible. + + The appearance can be configured using |colormap|s, the value of the |shader|, |faceted color| keys and the current |color| and/or |draw| / |fill| color. As for |mesh| plots, the special |color=mapped color| is installed for the faces. The stroking color for faceted plots can be set with |faceted color| (see below for details). + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + grid=major, + colormap/greenyellow] + \addplot3[surf,samples=30,domain=0:1] + {5*x*sin(2*deg(x)) * y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[surf,faceted color=blue] {x+y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colormap/cool] + \addplot3[surf,samples=10,domain=0:1, + shader=interp] + {x*(1-x)*y*(1-y)}; + \end{axis} +\end{tikzpicture} +\begin{tikzpicture} + \begin{axis}[colormap/cool] + \addplot3[surf,samples=25,domain=0:1, + shader=flat] + {x*(1-x)*y*(1-y)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[grid=major] + \addplot3[surf,shader=interp, + samples=25,domain=0:2,y domain=0:1] + {exp(-x) * sin(pi*deg(y))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[grid=major] + \addplot3[surf,shader=faceted, + samples=25,domain=0:2,y domain=0:1] + {exp(-x) * sin(pi*deg(y))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Details about the shading algorithm are provided below in the documentation of |shader|. + + Surface plots use the |mesh legend| style to create legend images. +\end{plottype} + +\begin{pgfplotskey}{shader=\mchoice{flat,interp,faceted,flat corner,flat mean} (initially faceted)} + Configures the shader used for surface plots. The shader determines how the color data available at each single vertex is used to fill the surface patch. + + The simplest choice is to use one fill color for each segment, the choice |flat|. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[surf,shader=flat, + samples=10,domain=0:1] + {x^2*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + \noindent The |flat| shader provides full support of |z buffer|ing, that means it does also support the choice |z buffer=sort|. There are (currently) two possibilities to determine the single color for every segment: + \begin{description} + \item[\declaretext{flat corner}] Uses the color data of one vertex to color the segment. It is not defined which vertex is used here\footnote{\PGFPlots\ just uses the last vertex encountered in its internal processings -- but after any $z$ buffer reorderings.}. + + \item[\declaretext{flat mean}] Uses the mean of all four color data values as segment color. This is the initial value as it provides symmetric colors for symmetric functions. + \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 Gouraud shading (bilinear interpolation) to fill the segments. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[surf,shader=interp, + samples=10,domain=0:1] + {x^2*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The |shader=interp| setting requires a special low--level shading implementation which is currently (only) available for the postscript driver \declaretext{pgfsys-dvips.def} and the |pdflatex| driver \declaretext{pgfsys-pdftex.def}. For other drivers, the choice |shader=interp| will result in a warning and is equivalent to |shader=flat mean|. + + + + Finally, the choice |shader=faceted| uses a constant fill color for every mesh segment (as for |flat|) and the value of the key |/pgfplots/faceted color| to draw the connecting mesh elements: +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[surf,shader=faceted, + samples=10,domain=0:1] + {x^2*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + + \paragraph{Details:} + \begin{itemize} + \item The choice |shader=faceted| is the same as |shader=flat| -- except that it uses a special draw color. + + So, |shader=faceted| has the same effect as + + |shader=flat,draw=\pgfkeysvalueof{/pgfplots/faceted color}|. + + \item The |flat| shader uses the current |draw| and |fill| colors. They are set with |color=mapped color| and can be overruled with |draw=|\meta{draw color} and |fill=|\meta{fill color}. The |mapped color| always contains the color of the color map. + + \item The |interp| shader does not support mesh colors and it uses the current color map in any case (it simply ignores the values of |draw| and |fill|). + + \item You easily add |mark=|\meta{plot mark} to mesh and/or surface plots or even colored plot marks with |scatter|. The scatter plot feature will use the same color data as for the surface. + + But: Markers and surfaces do not share the same depth information. They are drawn on top of each other. + + \item For surface plots with lots of points, |shader=interp| produces smaller |pdf| documents, requires less compilation time in \TeX\ and requires less time to display in Acrobat Reader. + + \item The postscript driver did not work when I tried to write hex encoded 32 bit binary coordinates into the shading. So, the postscript driver \emph{truncates} coordinates to 24 bit -- which might result in a loss of precision (the truncation is not very intelligent). See the |surf shading/precision| key for details. To improve compatibility, this 24 bit truncation algorithm is enabled by default. + \end{itemize} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[surf,shader=flat, + draw=black, + samples=10,domain=0:1] + {x^2*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[surf,shader=faceted, + scatter,mark=*, + samples=10,domain=0:1] + {x^2*y}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + +\begin{pgfplotskey}{faceted color=\marg{color name} (initially mapped color!80!black)} + Defines the color to be used for meshes of faceted surface plots. +\end{pgfplotskey} + +\begin{pgfplotskey}{surf shading/precision=\mchoice{pdf,postscript,ps} (initially postscript)} + A key to configure how the low level driver for |shader=interp| writes its data. The choice |pdf| uses 32 bit binary coordinates (which is lossless). The resulting |.pdf| files appear to be correct, but they can't be converted to postscript -- the converter software always complaints about an error. + + The choice |postscript| (or, in short, |ps|) uses 24 bit truncated binary coordinates. This results in both, readable |.ps| and |.pdf| files. However, the truncation is lossy. + + If anyone has ideas how to fix this problem: let me know. As far as I know, postscript should accept 32 bit coordinates, so it might be a mistake in the shading driver. +\end{pgfplotskey} + +\subsubsection{Parameterized Plots} +Parameterized plots use the same plot types as documented in the preceding sections: both, mesh and surface plots are actually special parameterized plots where $x$ and $y$ are on cartesian grid points. + +Parameterized plots just need a special way to provide the coordinates: + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[view={60}{30}] + \addplot3+[domain=0:5*pi,samples=60,samples y=0] + ({sin(deg(x))}, + {cos(deg(x))}, + {2*x/(5*pi)}); + \end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent The preceding example uses |samples y=0| to indicate that a line shall be samples instead of a matrix. The curly braces are necessary because \TeX\ can't nest round braces. The single expressions here are used to parameterize the helix. + +Another example follows. Note that |z buffer=sort| is a necessary method here. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[view={60}{30}] + \addplot3[mesh,z buffer=sort, + samples=20,domain=-1:0,y domain=0:2*pi] + ({sqrt(1-x^2) * cos(deg(y))}, + {sqrt( 1-x^2 ) * sin(deg(y))}, + x); +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[view={60}{30}] + \addplot3[mesh,z buffer=sort, + scatter,only marks,scatter src=z, + samples=30,domain=-1:1,y domain=0:2*pi] + ({sqrt(1-x^2) * cos(deg(y))}, + {sqrt( 1-x^2 ) * sin(deg(y))}, + x); +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[view={60}{30}] + \addplot3[surf,shader=flat,z buffer=sort, + samples=30,domain=-1:0,y domain=0:2*pi] + ({sqrt(1-x^2) * cos(deg(y))}, + {sqrt( 1-x^2 ) * sin(deg(y))}, + x); +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\subsubsection{About 3D Const Plots and 3D Bar Plots} +There are currently \emph{no} equivalents of |const plot| and its variants or the bar plot types like |ybar| for three dimensional axes, sorry. + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex new file mode 100644 index 00000000000..9c8c9ccb9ea --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex @@ -0,0 +1,371 @@ + +\subsection{Alignment Options and Bounding Box Control} +\label{pgfplots:sec:align} + +\subsubsection{Basic Alignment} +Alignment works with two main methods: a coordinate where the axis shall be drawn and an ``anchor'' inside of the axis which shall be drawn at this particular coordinate. This methodology is common for each \Tikz\ node -- and an axis is nothing but a (special) \Tikz\ node. The coordinate can be specified using the |at| key, while the anchor can be specified with the |anchor| key. In most cases, it is sufficient to provide only an anchor -- unless one needs more than one axis in the same picture environment. + +\begin{pgfplotskey}{at=\marg{coordinate expression}} +Assigns a position for the complete axis image. This option works similarly to the |at|-option of |\node[at=|\marg{coordinate expression}|]|, see~\cite{tikz}. The common syntax is |at={|\parg{x,y}|}|. + +The idea is to provide an \marg{coordinate expression} where the axis will be placed. The axis' anchor will be placed at \marg{coordinate expression}. +\end{pgfplotskey} + +\begin{pgfplotskey}{anchor=\marg{name} (initially south west)} +\label{option:anchor}% +This option shifts the axis horizontally and vertically such that the axis anchor (a point on the axis) is placed at canvas coordinate $(0,0)$ (this is \emph{not} the logical coordinate, it is an image coordinate). For users who are familiar with \Tikz: an axis is actually a very special node, so anchors work as in~\cite{tikz}. + +Anchors are useful in conjunction with horizontal or vertical alignment of plots, see the examples below. + +There are four sets of anchors available: anchors positioned on the axis bounding box, anchors on the outer bounding box and anchors which have one coordinate on the outer bounding box and the other one at a position of the axis rectangle. Finally, one can place anchors near the origin. + +{% +%\pgfplotsset{every picture/.append style={background rectangle/.style={help lines},show background rectangle}}% +\pgfplotstableread{pgfplots.testplot}\plottable +\def\plot{% + \begin{axis}[ + width=5cm, + name=test plot, + xlabel=$x$, + ylabel={$y$},% = \frac 12 \cdot x^3 - 4 x^2 -16 x$}, + legend style={at={(1.03,1)},anchor=north west}, + title=A test plot. + ] + \addplot table from{\plottable}; + %\addplot coordinates {(0,0) (1,1)}; + \addlegendentry{$f(x)$} + \addplot[red] plot[id=gnuplot_ppp,domain=-40:40,samples=120] gnuplot{10000*sin(x/3)}; + \addlegendentry{$g(x)$} + \end{axis} +}% +\def\showit#1#2{% + %\node[show them,#2] at (test plot.#1) {(s.#1)}; + \node[pin=#2:(s.#1),fill=black,circle,scale=0.3] at (test plot.#1) {}; +}% +\tikzstyle{every pin}=[opacity=0.5,fill=yellow,rectangle,rounded corners=3pt,font=\tiny]% +In more detail, we have +Anchors on the axis rectangle (the bounding box around the axis)\footnote{Versions prior to \PGFPlots\ v.1.3 did \emph{not} use the bounding box of the axis, they used axis coordinates to orient these anchors. This has been fixed. If you \emph{really} want to undo the bugfix, see \texttt{\protect\pgfmanualpdfref{compat/anchors}{compat/anchors}}.}, + \begin{center} + \begin{tikzpicture} + \plot + \showit{north}{90} + \showit{north west}{135} + \showit{west}{180} + \showit{south west}{225} + \showit{south}{270} + \showit{south east}{305} + \showit{east}{0} + \showit{north east}{45} + \showit{center}{90} + \end{tikzpicture} + \end{center} +Anchors on the outer bounding box, + \begin{center} + \begin{tikzpicture} + \plot + \showit{outer north}{90} + \showit{outer north west}{135} + \showit{outer west}{180} + \showit{outer south west}{225} + \showit{outer south}{270} + \showit{outer south east}{305} + \showit{outer east}{0} + \showit{outer north east}{45} + \showit{outer center}{90} + \end{tikzpicture} + \end{center} +There are anchors which have one coordinate on the outer bounding box, and one on the axis rectangle, + \begin{center} + \begin{tikzpicture} + \plot + {\pgfplotsset{every pin/.append style={pin distance=1cm}}% + \showit{above north}{90} + }% + \showit{above north east}{90} + \showit{right of north east}{0} + \showit{right of east}{0} + \showit{right of south east}{0} + \showit{below south east}{-90} + {\pgfplotsset{every pin/.append style={pin distance=1cm}}% + \showit{below south}{-90} + }% + \showit{below south west}{-90} + \showit{left of south west}{180} + \showit{left of west}{180} + \showit{left of north west}{180} + \showit{above north west}{90} + \end{tikzpicture} + \end{center} +And finally, we have origin anchors which are especially useful when axis lines pass through the origin, + \begin{center} + \begin{tikzpicture} + \begin{axis}[ + name=test plot, + axis x line=center, + axis y line=center, + enlargelimits=false, + minor tick num=3, + tick style={semithick}, + tick align=center, + xlabel=$x$, + ylabel=$y$, + every axis x label/.style={at={(current axis.right of origin)},anchor=north east}, + every axis y label/.style={at={(current axis.above origin)},anchor=north east}, + inner axis line style={->}, + ] + \addplot+[domain=-2:5] {20*x}; + \end{axis} + {\pgfplotsset{every pin/.append style={pin distance=1cm}}% + \showit{above origin}{45} + }% + \showit{right of origin}{45} + {\pgfplotsset{every pin/.append style={pin distance=1cm}}% + \showit{below origin}{0} + }% + \showit{left of origin}{135} + \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. + +\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. +} + +\subsubsection{Vertical alignment with \texttt{baseline}} +\label{sec:align}% +\pgfmanualpdflabel{/tikz/baseline}{}% +The default axis anchor is |south west|, which means that the picture coordinate $(0,0)$ is the lower left corner of the axis. As a consequence, the \Tikz\ option ``|baseline|'' allows vertical alignment of adjacent plots: +\begin{codeexample}[] +\pgfplotsset{domain=-1:1} +\begin{tikzpicture} + \begin{axis}[xlabel=A normal sized $x$ label] + \addplot[smooth,blue,mark=*] {x^2}; + \end{axis} +\end{tikzpicture}% +\hspace{0.15cm} +\begin{tikzpicture} + \begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }] + \addplot[smooth,blue,mark=*] {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\pgfplotsset{domain=-1:1} +\begin{tikzpicture}[baseline] + \begin{axis}[xlabel=A normal sized $x$ label] + \addplot[smooth,blue,mark=*] {x^2}; + \end{axis} +\end{tikzpicture}% +\hspace{0.15cm} +\begin{tikzpicture}[baseline] + \begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }] + \addplot[smooth,blue,mark=*] {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +The |baseline| option configures \Tikz\ to shift position $y=0$ to the text's baseline and the |south west| anchor shifts the axis such the $y=0$ is at the lower left axis corner. + +\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: +\begin{codeexample}[] +\begin{tikzpicture} +\pgfplotsset{every axis/.append style={ +cycle list={ + {red,only marks,mark options={ + fill=red,scale=0.8},mark=*}, + {black,only marks,mark options={ + fill=black,scale=0.8},mark=square*}}}} + +\begin{axis}[width=4cm,scale only axis, + name=main plot] +\addplot file + {plotdata/pgfplots_scatterdata1.dat}; +\addplot file + {plotdata/pgfplots_scatterdata2.dat}; +\addplot[blue] coordinates { + (0.093947, -0.011481) + (0.101957, 0.494273) + (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)}, + anchor=north west, + width=4cm,scale only axis,height=0.8cm, + ytick=\empty] + +\addplot file + {plotdata/pgfplots_scatterdata1_latent.dat}; +\addplot file + {plotdata/pgfplots_scatterdata2_latent.dat}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + +\subsubsection{Bounding box restrictions} +Bounding box restrictions can be realized with several methods of \PGF: +\begin{enumerate} + \item The |overlay| option, + \item The |pgfinterruptboundingbox| environment, + \item The |\useasboundingbox| path. +\end{enumerate} +\begin{key}{/tikz/overlay} +\index{Bounding Box Control!Excluding Image Parts} + A special key of \PGF\ which disables bounding box updates for (parts of) the image. The effect is that those parts are an ``overlay'' over the document. + + For \PGFPlots, |overlay| can be useful to position legends or other axis descriptions outside of the axis~-- without affecting its size (and without affecting alignment). + +For example, one may want to include only certain parts of the axis into the final bounding box. This would allow horizontal alignment (centering): +\begin{codeexample}[] +\begin{tikzpicture}% + \begin{axis}[ + title=A title, + ylabel style={overlay}, + yticklabel style={overlay}, + xlabel={$x$}, + ylabel={$y$}, + legend style={at={(0.5,0.97)}, + anchor=north,legend columns=-1}, + domain=-2:2 + ] + \addplot {x^2}; + \addplot {x^3}; + \addplot {x^4}; + \legend{$x^2$,$x^3$,$x^4$} + \end{axis} +\end{tikzpicture}% +\end{codeexample} +\noindent Now, the left axis descriptions ($y$ label and $y$ ticks) stick out of the bounding box. + +The following example places a legend somewhere without affecting the bounding box. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + domain=0:6.2832,samples=200, + legend style={ + overlay, + at={(-0.5,0.5)}, + anchor=center}, + every axis plot post/.append style={mark=none}, + enlargelimits=false] + + \addplot {sin(deg(x)+3)+rand*0.05}; + \addplot {cos(deg(x)+2)+rand*0.05}; + \legend{Signal 1,Signal 2} + \end{axis} +\end{tikzpicture} +\end{codeexample} + + More information about the |overlay| option can be found in the \PGF\ manual~\cite{tikz}. +\end{key} + + +\begin{environment}{{pgfinterruptboundingbox}} +\label{sec:bounding:box:example}% +\index{Bounding Box Control} +\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|. +\begin{codeexample}[] +\setlength{\fboxsep}{0pt}% +\fbox{% +\begin{tikzpicture}% + \begin{pgfinterruptboundingbox} + \begin{axis}[ + name=my plot, + 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} + \end{pgfinterruptboundingbox} + + \useasboundingbox + (my plot.below south west) + rectangle (my plot.above north east); +\end{tikzpicture}% +}% +\end{codeexample}% +}% +The |pgfinterruptboundingbox| environment does not include its content into the image's bounding box, and |\useasboundingbox| sets the pictures bounding box to the following argument (see~\cite{tikz}). +\end{environment} + +\end{pgfplotskey} + +\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. + +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|. + +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. + +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} + +\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} 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 new file mode 100644 index 00000000000..ae02b4c8bb8 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex @@ -0,0 +1,948 @@ + + +\subsection{The Axis-Environments} +There is an axis environment for linear scaling, two for semi-logarithmic scaling and one for double-logarithmic scaling. +\begin{environment}{{tikzpicture}\oarg{options of tikz}} + This is the graphics environment of \Tikz. It produces a single picture and encloses also every axis. + + Instead of using the environment version, there is also a shortcut command + + \declareandlabel{\tikz}\marg{picture content} + + which can be used alternatively. +\end{environment} + +\begin{environment}{{axis}\oarg{options}} + The axis environment for normal plots with linear axis scaling. + + The `|every linear axis|' style key can be modified with +\begin{codeexample}[code only] +\pgfplotsset{every linear axis/.append style={...}} +\end{codeexample} +to install styles specifically for linear axes. These styles can contain both \Tikz- and \PGFPlots\ options. +\end{environment} + +\begin{environment}{{semilogxaxis}\oarg{options}} +The axis environment for logarithmic scaling of~$x$ and normal scaling of~$y$. +Use +\begin{codeexample}[code only] +\pgfplotsset{every semilogx axis/.append style={...}} +\end{codeexample} +to install styles specifically for the case with |xmode=log|, |ymode=normal|. + +The logarithmic scaling means to apply the natural logarithm (base $e$) to each $x$ coordinate. Furthermore, ticks will be typeset as $10^{\text{\meta{exponent}}}$, see section~\ref{sec:number:printing} for more details. +\end{environment} + +\begin{environment}{{semilogyaxis}\oarg{options}} +The axis environment for normal scaling of~$x$ and logarithmic scaling of~$y$, + +The style `|every semilogy axis|' will be installed for each such plot. + +The same remarks as for |semilogxaxis| apply here as well. +\end{environment} + +\begin{environment}{{loglogaxis}\oarg{options}} +The axis environment for logarithmic scaling of both, $x$~and~$y$ axes, +As for the other axis possibilities, there is a style `|every loglog axis|' which is installed at the environment's beginning. + +The same remarks as for |semilogxaxis| apply here as well. +\end{environment} + +\noindent +They are all equivalent to +\begin{codeexample}[code only] +\begin{axis}[ + xmode=log|normal, + ymode=log|normal] +... +\end{axis} +\end{codeexample} +\noindent +with properly set variables `|xmode|' and `|ymode|' (see below). + +\subsection{The \protect\texttt{\protect\textbackslash addplot} Command: Coordinate Input} +\label{sec:addplot}% +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ymin=0,ymax=1,enlargelimits=false] +\addplot + [blue!80!black,fill=blue,fill opacity=0.5] +coordinates +{(0,0.1) (0.1,0.15) (0.2,0.5) (0.3,0.62) + (0.4,0.56) (0.5,0.58) (0.6,0.65) (0.7,0.6) + (0.8,0.58) (0.9,0.55) (1,0.52)} +|- (axis cs:0,0) -- cycle; + +\addplot + [red,fill=red!90!black,opacity=0.5] +coordinates +{(0,0.25) (0.1,0.27) (0.2,0.24) (0.3,0.24) + (0.4,0.26) (0.5,0.3) (0.6,0.23) (0.7,0.2) + (0.8,0.15) (0.9,0.1) (1,0.1)} +|- (axis cs:0,0) -- cycle; + +\addplot[green!20!black] coordinates + {(0,0.4) (0.2,0.75) (1,0.75)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[id=parable,domain=-5:5] + gnuplot{4*x**2 - 5} + node[pin=180:{$4x^2-5$}]{}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot3[surf,domain=0:360,samples=40] + {sin(x)*sin(y)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colormap/redyellow,colorbar] + \addplot3[surf, + domain=0:360,samples=40] + {sin(x)*sin(y)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[view={60}{30}] + \addplot3[surf,shader=flat, + samples=20, + domain=-1:0,y domain=0:2*pi, + z buffer=sort] + ({sqrt(1-x^2) * cos(deg(y))}, + {sqrt( 1-x^2 ) * sin(deg(y))}, + x); +\end{axis} +\end{tikzpicture} +\end{codeexample} + +Inside of an axis environment, the |\addplot| command is the main user interface. It comes in two variants: |\addplot| for twodimensional visualization and \verbpdfref{\addplot3} for threedimensional visualization. + +\begin{command}{\addplot\oarg{options} \meta{input data} \meta{trailing path commands};} +\label{cmd:pgfplots:addplot} +This is the main plotting command, available within each axis environment. It can be used one or more times within an axis to add plots to the current axis. There is also an \verbpdfref{\addplot3} command which is described in section~\ref{sec:3d}. + +It reads point coordinates from one of the available input sources specified by \meta{input data}, updates limits, remembers \meta{options} for use in a legend (if any) and applies any necessary coordinate transformations (or logarithms). + +The \meta{options} can be omitted in which case the next entry from the |cycle list| will be inserted as \meta{options}. These keys characterize the plot's type like linear interpolation, smooth plot, constant interpolation, bar plot, mesh plots, surface plots or whatever and define colors, markers and line specifications\footnote{In version 1.2.2 and earlier, there was an explicit distiction between ``behaviour'' options like error bars, domain, number of samples etc.\ and ``style options'' like color, line width, markers etc. This distiction is obsolete now, simply collect everything into \meta{options}.}\index{Behavior Options}\index{Options!Distinction Behavior, Style Options}. Plot variants like error bars, the number of samples or a sample domain can also be configured in \meta{options}. + +The \meta{input data} is one of several coordinate input tools which are described in more detail below. Finally, if |\addplot| successfully processed all coordinates from \meta{input data}, it generates \Tikz\ paths to realize the drawing operations. Any \meta{trailing path commands} are appended to the final drawing command, allowing to continue the \Tikz\ path (from the last plot coordinate). + +\noindent +Some more details: +\begin{itemize} + \item The style |/pgfplots/every axis plot| will be installed at the beginning of \meta{options}. That means you can use +\begin{codeexample}[code only] +\pgfplotsset{every axis plot/.append style={...}} +\end{codeexample} + to add options to all your plots - maybe to set line widths to |thick|. Furthermore, if you have more than one plot inside of an axis, you can also use +\begin{codeexample}[code only] +\pgfplotsset{every axis plot no 3/.append style={...}} +\end{codeexample} + to modify options for the plot with number~$3$ only. The first plot in an axis has number~$0$. + \item The \meta{options} are remembered for the legend. They are available as `\declareandlabel{current plot style}' as long as the path is not yet finished or in associated error bars. + \item See subsection~\ref{sec:markers} for a list of available markers and line styles. + \item For log plots, \PGFPlots\ will compute the natural logarithm $\log(\cdot)$ numerically using a floating point unit developed for this purpose\footnote{This floating point unit is available as \Tikz\ library as part of \Tikz.}. For example, the following numbers are valid input to |\addplot|. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{loglogaxis} +\addplot coordinates { + (769, 1.6227e-04) + (1793, 4.4425e-05) + (4097, 1.2071e-05) + (9217, 3.2610e-06) + (2.2e5, 2.1E-6) + (1e6, 0.00003341) + (2.3e7, 0.00131415) +}; +\end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + You can represent arbitrarily small or very large numbers as long as its logarithm can be represented as a \TeX-length (up to about~$16384$). Of course, any coordinate~$x\le 0$ is not possible since the logarithm of a non-positive number is not defined. Such coordinates will be skipped automatically (using the initial configuration |unbounded coords=discard|). + + \item For normal (non--logarithmic) axes, \PGFPlots\ applies floating point arithmetics to support large or small numbers like 0.00000001234 or $1.234\cdot 10^{24}$. Its number range is much larger than \TeX's native support for numbers. The relative precision is between $4$ and $7$ significant decimal digits for the mantisse. + + As soon as the axes limits are completely known, \PGFPlots\ applies a transformation which maps these floating point numbers into \TeX-precision using transformations + \[ T_x(x) = 10^{s_x} \cdot x - a_x + \text{ and } T_y(y) = 10^{s_y} \cdot y - a_y + \text{ and (for 3D plots) } T_z(y) = 10^{s_z} \cdot z - a_z + \] + with properly chosen integers $s_x, s_y, s_z \in \Z$ and shifts $a_x,a_y, a_z\in \R$. Section~\ref{sec:disabledatascaling} contains a description of |disabledatascaling| and provides more details about the transformation. + \index{Accuracy!Floating Point in \PGFPlots}% + + \item Some of the coordinate input routines use the powerful |\pgfmathparse| feature of \pgfname\ to read their coordinates, among them |plot coordinates|, |plot expression| and |plot table|. This allows to use mathematical expressions as coordinates which will be evaluated using the floating point routines (this applies to logarithmic and linear scales). + + \item If you did not specify axis limits manually, |\addplot| will compute them automatically. + The automatic computation of axis limits works as follows: + \begin{enumerate} + \item Every coordinate will be checked. Care has been taken to avoid \TeX's limited numerical capabilities. + \item Since more than one |\addplot| command may be used inside of |\begin{axis}...\end{axis}|, all drawing commands will be postponed until |\end{axis}|. + \end{enumerate} +\end{itemize} +\end{command} + +\begin{addplot+} +Does the same like |\addplot[|\meta{options}|] ...;| except that \meta{options} are \emph{appended} to the arguments which would have been taken for |\addplot ...| (the element of the default list). + +Thus, you can combine |cycle list| and \meta{options}. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot {sin(deg(x))}; +\end{axis} +\end{tikzpicture} + +\begin{tikzpicture} +\begin{axis} +\addplot+[only marks] {sin(deg(x))}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{addplot+} + +\subsubsection{Coordinate Lists} +\label{pgfplots:providing:input} + +\begin{addplotoperation}[]{coordinates}{\marg{coordinate list}} +\label{pgfplots:addplot:coordinates} +The `|plot coordinates|' command is like that provided by \Tikz\ and reads its input data from a sequence of point coordinates, encapsulated in round braces. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot coordinates { + (0,0) + (0.5,1) + (1,2) +}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent The coordinates can be numbers, but they can also contain mathematical expressions like |sin(0.5)| or |\h*8| (assuming you defined |\h| somewhere). However, expressions which involve round braces need to be encapsulated in a further set of curly braces, for example |({sin(0.5)},{cos(0.1)})|. + +You can also supply error coordinates (reliability bounds) if you are interested in error bars. Simply append the error coordinates with `\declareandlabel{+-} \parg{ex,ey}' (or |+- |\parg{ex,ey,ez}) to the associated coordinate: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[error bars/.cd,x dir=both,x explicit] +coordinates { + (0,0) +- (0.1,0) + (0.5,1) +- (0.4,0.2) + (1,2) + (2,5) +- (1,0.1) +}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +or +\begin{codeexample}[code only] +\addplot coordinates { + (900,1e-6) +- (0.1,0.2) + (2600,5e-7) +- (0.2,0.5) + (4000,7e-8) +- (0.1,0.01) +}; +\end{codeexample} +These error coordinates are only used in case of error bars, see section~\ref{sec:errorbars}. You will also need to configure whether these values denote absolute or relative errors. + +The coordinates as such can be numbers as |+5|, |-1.2345e3|, |35.0e2|, |0.00000123| or |1e2345e-8|. They are not limited to \TeX's precision. + +Furthermore, |coordinates| allows to define ``meta data'' for each coordinate. The interpretation of meta data depends on the visualization technique: for scatter plots, meta data can be used to define colors or style associations for every point (see page~\pageref{pgfplots:scatterclasses} for an example). Meta data (if any) must be provided after the coordinates and after error bar bounds (if any) in square brackets: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[scatter,scatter src=explicit] coordinates { + (900,1e-6) [1] + (2600,5e-7) [2] + (4000,7e-8) [3] +}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +Please refer to the documentation of |point meta| on page~\pageref{pgfplots:point:meta} for more information about per point meta data. +\end{addplotoperation} + +\begin{pgfplotskey}{plot coordinates/math parser=\mchoice{true,false} (initially true)} + Allows to turn off support for mathematical expressions in every coordinate inside of |plot coordinates|. This might be necessary if coordinates are not in numerical form (or if you'd like to improve speed). + + It is necessary to disable |plot coordinates/math parser| if you use some sort of symbolic transformations (i.e. text coordinates). +\end{pgfplotskey} + +\subsubsection{Reading Coordinates From Files} + +\begin{addplotoperation}[]{file}{\marg{name}} +\label{pgfplots:addplot:file} +\PGFPlots\ supports two ways to read plot coordinates of external files, and one of them is similar to the \Tikz-command `|plot file|'. It is to be used like +\begin{codeexample}[code only] +\addplot file {datafile.dat}; +\end{codeexample} +where \marg{name} is a text file with at least two columns which will be used as $x$ and $y$ coordinates. Lines starting with `|%|' or `|#|' are ignored. Such files are often generated by \textsc{gnuplot}: +\begin{codeexample}[code only] +#Curve 0, 20 points +#x y type +0.00000 0.00000 i +0.52632 0.50235 i +1.05263 0.86873 i +1.57895 0.99997 i +... +9.47368 -0.04889 i +10.00000 -0.54402 i +\end{codeexample} +This listing has been copied from~\cite[section~16.4]{tikz}. + +Plot file accepts one optional argument, + +\begin{codeexample}[code only] +\addplot file[skip first] {datafile.dat}; +\end{codeexample} + +\noindent +which allows to skip over a non-comment header line. This allows to read the same input files as |plot table| by skipping over column names. Please note that comment lines do not count as lines here. + +The input method |plot file| can also read meta data for every coordinate. As already explained for |plot coordinates| (see above), meta data can be used to change colors or other style parameters for every marker separately. Now, if |point meta| is set to |explicit| or to |explicit symbolic| and the input method is |plot file|, one further element will be read from disk -- for every line. Meta data is always the last element which is read. See page~\pageref{pgfplots:scatter:src} for information and examples about per point meta data and page~\pageref{pgfplots:scatterclasses} for an application example using |scatter/classes|. + + +Plot file is very similar to |plot table|: you can achieve the same effect with +\begin{codeexample}[code only] +\addplot table[x index=0,y index=1,header=false] {datafile.dat}; +\end{codeexample} +\noindent Due to its simplicity, |plot file| is slightly faster while |plot table| allows higher flexibility. + +Technical note: every opened file will be protocolled into your log file. +\end{addplotoperation} + +\begin{pgfplotskeylist}{% + plot file/skip first=\mchoice{true,false} (initially false),% + plot file/ignore first=\mchoice{true,false} (initially false)} + The two keys can be provided as arguments to |\addplot file[|\meta{options}|] |\marg{filename}|;| to skip the first non-comment entry in the file. They are equivalent. + If you provide them in this context, the prefix |/pgfplots/plot file| can be omitted. +\end{pgfplotskeylist} + +\subsubsection{Reading Coordinates From Tables} + +\begin{addplotoperation}[]{table}{\oarg{column selection}\marg{file}} +\label{pgfplots:addplot:table} +The use of `|plot table|' is similar in spirit to `|plot file|', but its flexibility is higher. Given a data file like +\begin{codeexample}[code only] +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{codeexample} +one may want to plot `|dof|' versus `|L2|' or `|dof|' versus `|Lmax|'. This can be done by +\begin{codeexample}[code only] +\begin{tikzpicture} +\begin{loglogaxis}[ + xlabel=Dof, + ylabel=$L_2$ error] +\addplot table[x=dof,y=L2] {datafile.dat}; +\end{loglogaxis} +\end{tikzpicture} +\end{codeexample} +or +\begin{codeexample}[code only] +\begin{tikzpicture} +\begin{loglogaxis}[ + xlabel=Dof, + 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: +\begin{codeexample}[code only] +\pgfplotstableread{datafile.dat}\table +... +\addplot table[x=dof,y=L2] from \table; +... +\addplot table[x=dof,y=Lmax] from \table; +... +\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: +\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 more than~$200$ data points (rows), you should always use file input (and reload if necessary). +\end{enumerate} + +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] +\addplot table[x index=2,y index=3] {datafile.dat}; +\addplot table[x=dof,y index=2] {datafile.dat}; +\end{codeexample} + +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 It is possible to read error coordinates from tables as well. Simply add options `|x error|', `|y error|' or `|x error index|'/`|y error index|' to \marg{source columns}. See section~\ref{sec:errorbars} for details about error bars. + \item It is possible to read per point meta data (usable in |scatter src|, see page~\pageref{pgfplots:scatter:src}) as has been discussed for |plot coordinates| and |plot file| above. The meta data column can be provided using the |meta| key (or the |meta index| key). + \item Use |plot table[|\meta{source columns}|] from |\marg{\textbackslash macro} to use a pre--read table. Tables can be read using +\begin{codeexample}[code only] +\pgfplotstableread{datafile.dat}\macroname. +\end{codeexample} + The keyword `|from|' can be omitted. + + \item The accepted input format of those tables is as follows: + \begin{itemize} + \item Columns are usually separated by white spaces (at least one tab or space). + + 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} + + 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. + \item The first line will be checked if it contains numerical data. If there is a column in the first line which is \emph{no} number, the complete line is considered to be a header which contains column names. Otherwise it belongs to the numerical data and you need to access column indices instead of names. + + \item There is future support for a second header line which must start with `|$flags |'. Currently, such a line is ignored. It may be used to provide number formatting hints like precision and number format if those tables shall be typeset using |\pgfplotstabletypeset| (see the manual for \PGFPlotstable). + \item The accepted number format is the same as for `|plot coordinates|', see above. + \item If you omit column selectors, the default is to plot the first column against the second. That means |plot table| does exactly the same job as |plot file| for this case. + \item If you need unbalanced columns, simply use |nan| as ``empty cell'' placeholder. These coordinates will be skipped in plots. + \index{Unbalanced Columns}% + \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''. + + 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} + +\begin{pgfplotskey}{table/header=\mchoice{true,false} (initially true)} + Allows to disable header identification for |plot table|. See above. +\end{pgfplotskey} +\begin{pgfplotsxykeylist}{table/\x=\marg{column name}, + table/\x\ index=\marg{column index}} + These keys define the sources for |plot table|. If both, column names and column indices are given, column names are preferred. Column indexing starts with~$0$. The initial setting is to use |x index=0| and |y index=1|. + + Please note that column \emph{aliases} will be considered if unknown column names are used. Please refer to the manual of \PGFPlotstable\ which comes with this package. +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykeylist}{table/\x\ expr=\marg{expression},table/meta expr=\marg{expression}} + These keys allow to combine the mathematical expression parser with file input. They are listed here to complete the list of table keys, but they are described in all detail in section~\ref{pgfplots:addplot:table:expr}. + + The key idea is to provide an \meta{expression} which depends on table data (possibly on all columns in one row). Only data within the same row can be used where columns are referenced with |\thisrow|\marg{column name} or |\thisrowno|\marg{column index}. + + Please refer to section~\ref{pgfplots:addplot:table:expr} for details. +\end{pgfplotsxykeylist} + + +\begin{pgfplotsxykeylist}{% + table/\x\ error=\marg{column name}, + table/\x\ error index=\marg{column index}, + table/\x\ error expr=\marg{math expression}} + These keys define input sources for error bars with explicit error values. + + The |x error| method provides an input column name (or alias), the |x error index| method provides input column \emph{indices} and |x error expr| works just as |table/x expr|: it allows arbitrary mathematical expressions which may depend on any number of table columns using |\thisrow|\marg{col name}. + + Please see section~\ref{sec:errorbars} for details about the usage of error bars. +\end{pgfplotsxykeylist} +\begin{pgfplotsxykeylist}{% + table/meta=\marg{column name}, + table/meta index=\marg{column index}} + These keys define input sources for per point meta data. Please see page~\pageref{pgfplots:scatter:src} for details about meta data or the documentation for |plot coordinates| and |plot file| for further information. +\end{pgfplotsxykeylist} +\begin{key}{/pgfplots/table/col sep=\mchoice{space,tab,comma,semicolon,colon,braces} (initially space)} + Allows to choose column separators for |plot table|. Please refer to the manual of \PGFPlotstable\ which comes with this package for details about |col sep|. +\end{key} +\begin{key}{/pgfplots/table/read completely=\marg{true,false} (initially false)} + Allows to customize \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''). + + \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} + +\subsubsection{Computing Coordinates with Mathematical Expressions} + +\begin{addplotoperation}[]{\marg{math expression}}{} +\pgfmanualpdflabel{plot expression}{} +\pgfmanualpdflabel{\textbackslash addplot expression}{} + This input method allows to provide mathematical expressions which will be sampled. But unlike |plot gnuplot|, the expressions are evaluated using the math parser of \PGF, no external program is required. + + Plot expression samples |x| from the interval $[a,b]$ where $a$ and $b$ are specified with the |domain| key. The number of samples can be configured with |samples=|\meta{N} as for plot gnuplot. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \addplot {x^2 + 4}; + \addplot {-5*x^3 - x^2}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +Please note that \PGF's math parser uses degrees for trigonometric functions: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \addplot+[domain=0:360] + {sin(x)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent If you want to use radians, use +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \addplot+[domain=-pi:pi] + {sin(deg(x))}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent to convert the radians to degrees. The plot expression parser also accepts some more options like |samples at=|\marg{coordinate list} or |domain=|\meta{first}|:|\meta{last} which are described below. + +\paragraph{Remarks} +\begin{enumerate} + \item What really goes on is a loop which assigns the current sample coordinate to the macro |\x|. \PGFPlots\ defines a math constant |x| which always has the same value as |\x|. + + In short: it is the same whether you write |\x| or just |x| inside of math expressions. + + The variable name can be customized using |variable=\t| (the backslash is necessary!). Then, |t| will be the same as |\t|. +\index{x@\texttt{\textbackslash x} In Coordinate Expressions}% +%\index{y@\texttt{\textbackslash y} In Coordinate Expressions}% + + \item The complete set of math expressions can be found in the \PGF\ manual. The most important mathematical operations are + |+|, |-|, |*|, |/|, |abs|, |round|, |floor|, |mod|, |<|, |>|, |max|, |min|, |sin|, |cos|, |tan|, |deg| (conversion from radians to degrees), |rad| (conversion from degrees to radians), |atan|, |asin|, |acos|, |cot|, |sec|, |cosec|, |exp|, |ln|, |sqrt|, the constanst |pi| and |e|, |^| (power operation), |factorial|\footnote{Starting with \PGF\ versions newer than $2.00$, you can use the postfix operator \texttt{!} instead of \texttt{factorial}.}, |rand| (random between $-1$ and $1$), |rnd| (random between $0$ and $1$), number format conversions |hex|, |Hex|, |oct|, |bin| and some more. The math parser has been written by Mark Wibrow and Till Tantau~\cite{tikz}, the FPU routines have been developed as part of \PGFPlots. The documentation for both parts can be found in~\cite{tikz}. + + Please note, however, that trigonometric functions are defined in degrees. The character `|^|' is used for exponentiation (not `|**|' as in gnuplot). + + \item If the $x$ axis is logarithmic, samples will be drawn logarithmically. + + \item Please note that plot expression does not allow per point meta data (color data). +\end{enumerate} + +\paragraph{About the precision and number range:} +\index{Accuracy!High Precision for Plot Expression}% +\index{Errors!dimension too large}% + \index{Precision}\index{Floating Point Unit} Starting with version 1.2, |plot expression| uses a floating point unit. The FPU provides the full data range of scientific computing with a relative precision between $10^{-4}$ and $10^{-6}$. The |/pgf/fpu| key provides some more details. + + In case the |fpu| does not provide the desired mathematical function or is too slow\footnote{Or in case you find a bug$\dotsc$}, you should consider using the |plot gnuplot| method which invokes the external, freely available program |gnuplot| as desktop calculator. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[ + title={$\frac{1}{x^2}$}] + \addplot[blue,domain=1:1e30] + {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{semilogyaxis}[ + title={$e^x$ logarithmically plotted}] + \addplot[blue,domain=1:700] + {exp(x)}; + \end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} +\end{addplotoperation} + +\begin{addplotoperation}[]{expression}{\marg{math expr}} + The syntax + + |\addplot |\marg{math expression}|;| + + as short-hand equivalent for + + |\addplot expression |\marg{math expression}|;| +\end{addplotoperation} + +\begin{addplotoperation}[]{(\meta{$x$ expression},\meta{$y$ expression})}{} + A variant of \verbpdfref{\addplot expression} which allows to provide different coordinate expressions for the $x$ and $y$ coordinates. This can be used to generate parameterized plots. + + Please note that |\addplot (x,x^2)| is equivalent to |\addplot expression {x^2}|. + + Note further that since the complete point expression is surrounded by round braces, round braces for either \meta{$x$ expression} or \meta{$y$ expression} need special attention. You will need to introduce curly braces additionally to allow round braces: + + |\addplot (|\marg{$x$ expr}|, |\marg{$y$ expr}|, |\marg{$z$ expr}|);| +\end{addplotoperation} + +\begin{pgfplotskeylist}{% + domain=\meta{$x_1$}:\meta{$x_2$} (initially [-5:5]),% + y domain=\meta{$y_1$}:\meta{$y_2$}, + domain y=\meta{$y_1$}:\meta{$y_2$}} + Sets the function's domain(s) for |plot expression| and |plot gnuplot|. Two dimensional plot expressions are defined as functions $f\colon [x_1,x_2] \to \R$ and \meta{$x_1$} and \meta{$x_2$} are set with |domain|. Three dimensional plot expressions use functions $f\colon [x_1,x_2] \times [y_1,y_2] \to \R$ and \meta{$y_1$} and \meta{$y_2$} are set with |y domain|. If |y domain| is empty, $[y_1,y_2] = [x_1,x_2]$ is assumed for three dimensional plots (see page~\pageref{cmd:addplot3:expr} for details about three dimensional plot expressions). + + The keys |y domain| and |domain y| are the same. + + + The |domain| key won't be used if |samples at| is specified; |samples at| has higher precedence. + + + Please note that |domain| is not necessarily the same as the axis limits (which are configured with the |xmin|/|xmax| options). + + The |domain| keys are \emph{only} relevant for |gnuplot| and |plot expression|. In case you'd like to plot only a subset of other coordinate input routines, consider using the coordinate filter |restrict x to domain|. + + \paragraph{Remark for \Tikz-users:} |/pgfplots/domain| and |/tikz/domain| are independent options. Please prefer the \PGFPlots\ variant (i.e.\ provide |domain| to an axis, |\pgfplotsset| or a plot command). Since older versions also accepted something like |\begin{tikzpicture}[domain=|$\dotsc$|]|, this syntax is also accepted as long as no \PGFPlots\ |domain| key is set. +\end{pgfplotskeylist} + +\begin{pgfplotskeylist}{% + samples=\marg{number} (initially 25),% + samples y=\marg{number}} + Sets the number of sample points for |plot expression| and |plot gnuplot|. The |samples| key defines the number of samples used for line plots while the |samples y| key is used for mesh plots (three dimensional visualisation, see page~\pageref{cmd:addplot3:expr} for details). If |samples y| is not set explicitly, it uses the value of |samples|. + + The |samples| key won't be used if |samples at| is specified; |samples at| has higher precedence. + + The same special treatment of |/tikz/samples| and |/pgfplots/samples| as for the |domain| key applies here. See above for details. +\end{pgfplotskeylist} + +\begin{pgfplotskey}{samples at=\marg{coordinate list}} + Sets the $x$ coordinates for |plot expression| explicitly. This overrides |domain| and |samples|. + + The \marg{coordinate list} is a |\foreach| expression, that means it can contain a simple list of coordinates (comma--separated) but also complex |...| expressions like\footnote{Unfortunately, the \texttt{...} is somewhat restrictive when it comes to extended accuracy. So, if you have particularly small or large numbers (or a small distance), you have to provide a comma--separated list (or use the \texttt{domain} key).} +\begin{codeexample}[code only] +\pgfplotsset{samples at={5e-5,7e-5,10e-5,12e-5}} +\pgfplotsset{samples at={-5,-4.5,...,5}} +\pgfplotsset{samples at={-5,-3,-1,-0.5,0,...,5}} +\end{codeexample} + + The same special treatment of |/tikz/samples at| and |/pgfplots/samples at| as for the |domain| key applies here. See above for details. + + \paragraph{Attention:} |samples at| overrides |domain|, even if |domain| has been set \emph{after} |samples at|! Use |samples at={}| to clear \marg{coordinate list} and re-activate |domain|. +\end{pgfplotskey} + +\subsubsection{Mathematical Expressions And File Data} +\PGFPlots\ allows to combine `|plot table|' and `|plot expression|' to get both, file input and modifications by means of mathematical expressions. + +\begin{addplotoperation}[]{table}{\oarg{column selection and expressions}\marg{file}} +\label{pgfplots:addplot:table:expr} + Besides the already discussed possibility to provide a column selection by means of column names (|x||=|\meta{name} or |x index||=|\meta{index}, see section~\ref{pgfplots:addplot:table}), it is also possible to provide mathematical expressions as arguments. + + Mathematical expressions are specified with |x expr||=|\meta{expression} inside of \meta{column selection and expressions}. They can depend on zero, one or more columns of the input file. A column is referenced using the special command `|\thisrow|\marg{column name}' within \meta{expression} (or |\thisrowno|\meta{column index}). +\begin{codeexample}[vbox] +\pgfplotstabletypeset[columns={maxlevel,L2}]{plotdata/newexperiment1.dat} + +\begin{tikzpicture} + \begin{semilogyaxis}[ + xlabel=\texttt{maxlevel}$ + 10$ + ] + \addplot table + [x expr=\thisrow{maxlevel}+10, y=L2] + {plotdata/newexperiment1.dat}; + \end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} + + Besides |x expr|, there are keys |y expr|, |z expr| and |meta expr| where the latter allows to provide point meta data (which is used as |scatter src| or color data for surface plots etc.). + + Inside of \meta{expression}, the following macros can be used to access numerical data cells inside of the input file: + + \begin{command}{\thisrow\marg{column name}} + Yields the value of the column designated by \marg{column name}. There is no limit on the number of columns which can be part of a mathematical expression, but only values inside of the currently processed \emph{table row} can be used. + + It is possible to provide column aliases for \marg{column name} as described in the manual of \PGFPlotstable. + + The argument \meta{column name} has to denote either an existing column or one for which a column alias exists (see the manual of \PGFPlotstable). If it can't be resolved, the math parser yields an ``Unknown function'' error message. + \end{command} + \begin{command}{\thisrowno\marg{column index}} + Similar to |\thisrow|, this command yields the value of the column with index \marg{column index} (starting with $0$). + \end{command} + \begin{command}{\coordindex} + Yields the current index of the table row (starting with $0$). This does \emph{not} count header or comment lines. + \end{command} + \begin{command}{\lineno} + Yields the current line number (starting with $0$). This does also count header and comment lines. + \end{command} + + If |x index|, |x| and |x expr| (or the corresponding keys for |y|, |z| or |meta|) are combined, this is how they interact: + \begin{enumerate} + \item Column access via |x| has higher precedence than index access via |x index|. + \item Even if |x expr| is provided, the values of |x index| and |x| are still checked. Any value found using column name access or column index access is made available as |\columnx| (or |\columny|, |\columnz|, |\columnmeta|, resp.). However, the result of |x expr| is used as plot coordinate. + + This allows to access the cell values identified by |x| or |x index| using the ``pointer'' |\columnx|. I am not sure if this yields any advantage, but it is possible nevertheless. If in doubt, prefer using |\thisrow|\marg{column name}. + \end{enumerate} + + \paragraph{Attention:} If your table has less rows than two, you may need to set |x index={},y index={}| explicitly. This is a consequence of the fact that column name/index access is still applied even if an expression is provided. +\end{addplotoperation} + +\subsubsection{Computing Coordinates with Mathematical Expressions (gnuplot)} + +\begin{addplotoperation}[]{gnuplot}{\oarg{further options}\marg{gnuplot code}} +In contrast to |plot expression|, the |plot gnuplot| command\footnote{Note that |plot gnuplot| is actually a re-implementation of the |plot function| method known from \PGF. It also invokes \PGF\ basic layer commands.} employs the external program |gnuplot| to compute coordinates. The resulting coordinates are written to a text file which will be plotted with |plot file|. \PGF\ checks whether coordinates need to be re-generated and calls |gnuplot| whenever necessary (this is usually the case if you change the number of samples, the argument to |plot gnuplot| or the plotted domain\footnote{Please note that \PGFPlots\ produces slightly different files than \Tikz\ when used with \texttt{plot gnuplot} (it configures high precision output). You should use different \texttt{id} for \PGFPlots\ and \Tikz\ to avoid conflicts in such a case.}). + +The differences between |plot expression| and |plot gnuplot| are: +\begin{itemize} + \item |plot expression| does not require any external programs and requires no additional command line options. + \item |plot expression| does not produce a lot of temporary files. + \item |plot gnuplot| uses radians for trigonometric functions while |plot expression| has degrees. + \item |plot gnuplot| is faster. + \item |plot gnuplot| has a larger mathematical library. + \item |plot gnuplot| has a higher accuracy. However, starting with version 1.2, this is no longer a great problem. The new floating point unit for \TeX\ provides reasonable accuracy and the same data range as |gnuplot|. +\end{itemize} + +Since system calls are a potential danger, they need to be enabled explicitly using command line options, for example +\begin{codeexample}[code only] +pdflatex -shell-escape filename.tex. +\end{codeexample} +Sometimes it is called |shell-escape| or |enable-write18|. Sometimes one needs two slashes -- that all depends on your \TeX\ distribution. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot + gnuplot[id=sin]{sin(x)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{semilogyaxis} +\addplot gnuplot + [id=exp,domain=0:10]{exp(x)}; +\end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} + +The \meta{options} determine the appearance of the plotted function; these parameters also affect the legend. There is also a set of options which are specific to the gnuplot interface. These options are described in all detail in \cite[section~18.6]{tikz}. A short summary is shown below. + +Please note that |plot gnuplot| does not allow per point meta data (color data for each coordinate). + +Please refer to \cite[section~18.6]{tikz} for more details about |plot function| and the |gnuplot| interaction. + +\begin{pgfplotskey}{translate gnuplot=\mchoice{true,false} (initially true)} + Enables or disables automatic translation of the exponentiation operator `|^|' to `|**|'. + + This features allows to use |^| in |plot gnuplot| instead of gnuplot's |**|. +\end{pgfplotskey} +\end{addplotoperation} + +\begin{addplotoperation}[]{function}{\marg{gnuplot code}} + Use + + |\addplot function |\marg{gnuplot code}|;| + + as alias for + + |\addplot gnuplot |\marg{gnuplot code}|;| +\end{addplotoperation} + +\begin{key}{/tikz/id=\marg{unique string identifier}} + A unique identifier for the current plot. It is used to generate temporary filenames for |gnuplot| output. +\end{key} + +\begin{key}{/tikz/prefix=\marg{file name prefix}} + A common path prefix for temporary filenames (see \cite[section~18.6]{tikz} for details). +\end{key} + +\begin{key}{/tikz/raw gnuplot} + Disables the use of |samples| and |domain|. +\end{key} + +\subsubsection{Computing Coordinates with External Programs (shell)} + +\begin{addplotoperation}[]{shell}{\oarg{further options}\marg{shell commands}} +{\small \emph{An extension by Stefan Tibus}} + +In contrast to |plot gnuplot|, the |plot shell| command allows execution of arbitrary shell commands to compute coordinates. The resulting coordinates are written to a text file which will be plotted with |plot file|. \PGF\ checks whether coordinates need to be re-generated and executes the \meta{shell commands} whenever necessary. + +Since system calls are a potential danger, they need to be enabled explicitly using command line options, for example +\begin{codeexample}[code only] +pdflatex -shell-escape filename.tex. +\end{codeexample} +Sometimes it is called |shell-escape| or |enable-write18|. Sometimes one needs two slashes -- that all depends on your \TeX\ distribution. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot + shell[prefix=pgfshell_,id=cos]{awk 'BEGIN{ + pi=3.14159; N=10; + for(i=0;i<=N;i++) print i,cos(i/N*pi);}'}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[prefix=pgfshell_,id=replot] + shell{cat pgfshell_cos.out}; + % just reprint the result from above +\end{axis} +\end{tikzpicture} +\end{codeexample} + +The \meta{options} determine the appearance of the plotted function; these parameters also affect the legend. There is also a set of options which are specific to the gnuplot and the shell interface. These options are described in all detail in \cite[section~19.6]{tikz}. A short summary is shown below. +\end{addplotoperation} + +\begin{key}{/tikz/id=\marg{unique string identifier}} + A unique identifier for the current plot. It is used to generate temporary filenames for |shell| output. +\end{key} + +\begin{key}{/tikz/prefix=\marg{file name prefix}} + A common path prefix for temporary filenames (see \cite[section~19.6]{tikz} for details). +\end{key} + +\subsubsection{Using External Graphics as Plot Sources} + +\begin{addplotoperation}[]{graphics}{\marg{file name}} +\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/plot graphics/,}{}} + This plot type allows to extend the plotting capabilities of \PGFPlots\ beyond its own limitations. The idea is to generate the graphics as such (for example, a contour plot, a complicated shaded surface\footnote{See also section~\ref{sec:pgfplots:surfplots} for an overview of \PGFPlots\ methods to draw shaded surfaces.} or a large point cluster) with an external program like Matlab (tm) or |gnuplot|. The graphics, however, should \emph{not} contain an axis or descriptions. Then, we use |\includegraphics| and an \PGFPlots\ axis which fits exactly on top of the imported graphics. + + Of course, one could do this manually by providing proper scales and such. The operation |plot graphics| is intended so simplify this process. However the \emph{main difficulty} is to get images with correct bounding box. Typically, you will have to adjust bounding boxes manually. + + Let's start with an example: Suppose we use, for example, matlab to generate a surface plot like +\begin{codeexample}[code only] +[X,Y] = meshgrid( linspace(-3,3,500) ); +surf( X,Y, exp(-(X - Y).^2 - X.^2 ) ); +shading flat; view(0,90); axis off; +print -dpng external1 +\end{codeexample} + \noindent which is then found in |external1.png|. The |surf| command of Matlab generates the surface, the following commands disable the axis descriptions, initialise the desired view and export it. Viewing the image in any image tool, we see a lot of white space around the surface -- Matlab has a particular weakness in producing tight bounding boxes, as far as I know. Well, no problem: use your favorite image editor and crop the image (most image editors can do this automatically). We could use the free ImageMagick command + + |convert -trim external1.png external1.png| + + to get a tight bounding box. Then, we use + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[enlargelimits=false,axis on top] + \addplot graphics + [xmin=-3,xmax=3,ymin=-3,ymax=3] + {external1}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent to load the graphics\footnote{Please note that I don't have a Matlab license, so I used \texttt{gnuplot} to produce an equivalent replacement graphics.} just as if we would have drawn it with \PGFPlots. The |axis on top| simply tells \PGFPlots\ to draw the axis on top of any plots (see its description). + +Please note that \PGFPlots\ offers support for smaller surface plots as well which might be an option -- unless the number of samples is too large. See section~\ref{sec:pgfplots:surfplots} for details. + +\noindent However, external programs have the following advantages here: they are faster, allow more complexity and provide real $z$ buffering which is currently only simulated by \PGFPlots. Thus, it may help to consider |plot graphics| for complicated surface plots. + +Our first test was successful -- and not difficult at all because graphics programs can automatically compute the bounding box. There are a couple of free tools available which can compute tight bounding boxes for |.eps| or |.pdf| graphics: +\begin{enumerate} + \item The free vector graphics program |inkscape| can help here. Its feature ``File $\gg$ Document Properties: Fit page to selection'' computes a tight bounding box around every picture element. + + However, some images may contain a rectangular path which is as large as the bounding box (Matlab (tm) computes such |.eps| images). In this case, use the ``Ungroup'' method (context menu of |inkscape|) as often as necessary and remove such a path. + + Finally, save as |.eps|. + + However, |inkscape| appears to have problems with postscript fonts -- it substitutes them. This doesn't pose problems in this application because fonts shouldn't be part of such images -- the descriptions will be drawn by \PGFPlots. + + \item The tool |pdfcrop| removes surrounding whitespace in |.pdf| images and produces quite good bounding boxes. +\end{enumerate} + +\paragraph{Adjusting bounding boxes manually} +In case you don't have tools at hand to provide correct bounding boxes, you can still use \TeX\ to set the bounding box manually. Some viewers like |gv| provide access to low--level image coordinates. The idea is to determine the number of units which need to be removed and communicate these units to |\includegraphics|. + +I am aware of the following methods to determine bounding boxes manually: +\begin{description} + \item[inkscape] I am pretty sure that |inkscape| can do it. + \item[gv] The ghost script viewer |gv| always shows the postscript units under the mouse cursor. + \item[gimp] The graphics program |gimp| usually shows the cursor position in pixels, but it can be configured to display postscript points (|pt|) instead. +\end{description} + +Let's follow this approach in a further example. + + We use |gnuplot| to draw a (relatively stupid) example data set. The gnuplot script +\begin{codeexample}[code only] +set samples 30000 +set parametric +unset border +unset xtics +unset ytics +set output "external2.eps" +set terminal postscript eps color +plot [t=0:1] rand(0),rand(0) with dots notitle lw 5 +\end{codeexample} +\noindent generates |external2.eps| with a uniform random sample of size $30000$. As before, we import this scatter plot into \PGFPlots\ using |plot graphics|. Again, the bounding box is too large, so we need to adjust it (|gnuplot| can do this automatically, but we do it anyway to explain the mechanisms): + +Using |gv|, I determined that the bounding box needs to be shifted |12| units to the left and |9| down. Furthermore, the right end is |12| units too far off and the top area has about |8| units space wasted. This can be provided to the |trim| option of |\includegraphics|, and we use |clip| to clip the rest away: +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[axis on top,title=Graphics Import] + \addplot 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)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + So, |plot graphics| takes a graphics file along with options which can be passed to |\includegraphics|. Furthermore, it provides the information how to embed the graphics into an axis. The axis can contain any other |\addplot| command as well and will be resized properly. + + +\paragraph{Details about \texttt{plot graphics}:} + The loaded graphics file is drawn with + + |\node[/pgfplots/plot graphics/node] {\includegraphics[|\meta{options}|]|\marg{file name}|};| + + where the |node| style is a configurable style. The node is placed at the coordinate designated by |xmin|, |ymin|. + + 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. +\end{addplotoperation} +\begin{pgfplotsxykeylist}{ + plot graphics/\x min=\marg{coordinate}, + plot graphics/\x max=\marg{coordinate}} + These keys are required for |plot graphics| and provide information about the external data range. The graphics will be squeezed between these coordinates. The arguments are axis coordinates. +\end{pgfplotsxykeylist} + +\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{stylekey}{/pgfplots/plot graphics/node} + A predefined style used for the \Tikz\ node containing the graphics. The predefined value is +\begin{codeexample}[code only] +\pgfplotsset{ + plot graphics/node/.style={ + transform shape, + inner sep=0pt, + outer sep=0pt, + every node/.style={}, + anchor=south west, + at={(0pt,0pt)}, + rectangle + } +} +\end{codeexample} +\end{stylekey} + +\begin{pgfplotskey}{plot graphics} + This key belongs to the public low--level plotting interface. You won't need it in most cases. + + This key is similar to |sharp plot| or |smooth| or |const plot|: it installs a low--level plot--handler which expects exactly two points: the lower left corner and the upper right one. The graphics will be drawn between them. The graphics file name is expected as value of the |/pgfplots/plot graphics/src| key. The other keys described above need to be set correctly (excluding the limits, these are ignored at this level of abstraction). This key can be used independently of an axis. +\end{pgfplotskey} + +\begin{pgfplotskey}{plot graphics/lowlevel draw=\marg{width}\marg{height}} + A low--level interface for |plot graphics| which actually invokes |\includegraphics|. But there is no magic involved: the command is simply expected to draw a box of dimensions \meta{width} $\times$ \meta{height}. The coordinate system has already been shifted correctly. + + The initial configuration is + + |\includegraphics[|\meta{value of ``{\normalfont\texttt{plot graphics/includegraphics}}''}|,width=#1,height=#2]| + + \hspace{10pt}\marg{value of ``{\normalfont\texttt{plot graphics/src}}''}. + + Thus, you can tweak |plot graphics| to place any \TeX\ box of the desired dimensions into an axis between the provided minimum and maximum coordinates. It is not necessary to make use of the graphics file name or the options in the `|includegraphics|' key if you overwrite this lowlevel interface with + + |plot graphics/lowlevel draw/.code 2 args=|\marg{code which depends on \texttt{\#1} and \texttt{\#2}}. +\end{pgfplotskey} + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex new file mode 100644 index 00000000000..6c220b201ae --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axisdescription.tex @@ -0,0 +1,1866 @@ + +\subsection{Axis Descriptions} +Axis descriptions are labels for $x$ and $y$ axis, titles, legends and the like. Axis descriptions are drawn after the plot is finished and they are not subjected to clipping. + +\subsubsection{Placement of Axis Descriptions} +This section describes how to \emph{modify} the placement of titles, labels, legends and other axis descriptions. It may be skipped at first reading. + +There are different methods to place axis descriptions. One of them is to provide coordinates relative to the axis' rectangle such that |(0,0)| is the lower left corner and |(1,1)| is the upper right corner -- this is very useful for figure titles or legends. Coordinates of this type, i.e.\ without unit like |(0,0)| or |(1.03,1)|, are called |axis description cs| (the |cs| stands for ``coordinate system''). One other method is of primary interest for axis labels -- they should be placed near the tick labels, but it a way that they don't overlap or obscure tick labels. Furthermore, axis labels shall be placed such that they are automatically moved if the axis is rotated (or tick labels are moved to the right side of the figure). There is a special coordinate system to realize these two demands, the |ticklabel cs|. + +In the following, the two coordinate systems |axis description cs| and |ticklabel cs| are described in more details. It should be noted that |axis description cs| is used automatically, so it might never be necessary to use it explicitly. + + +\begin{coordinatesystem}{axis description cs} +\label{pgfplots:sec:axis:description:cs} + A coordinate system which is used to place axis descriptions. Whenever the option `|at={(|\meta{x}|,|\meta{y}|)}|' occurs in |label style|, |legend style| or any other axis description, |(|\meta{x}|,|\meta{y}|)| is interpreted to be a coordinate in |axis description cs|. + + The point $(0,0)$ is always the lower left corner of the tightest bounding box around the axis (without any descriptions or ticks) while the point $(1,1)$ is the upper right corner of this bounding box. + + In most cases, it is \emph{not} necessary to explicitly write |axis description cs| as it is the default coordinate system for any axis description. An example for how coordinates are placed is shown below. + +\begin{codeexample}[width=4cm] +% [See the TikZ manual if you'd like to learn about nodes and pins] +\begin{tikzpicture} + \tikzset{ + every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny}, + small dot/.style={fill=black,circle,scale=0.3} + } + \begin{axis}[ + clip=false, + title=How \texttt{axis description cs} works + ] + \addplot {x}; + + \node[small dot,pin=120:{$(0,0)$}] at (axis description cs:0,0) {}; + \node[small dot,pin=-30:{$(1,1)$}] at (axis description cs:1,1) {}; + \node[small dot,pin=-90:{$(1.03,0.5)$}] at (axis description cs:1.03,0.5) {}; + \node[small dot,pin=125:{$(0.5,0.5)$}] at (axis description cs:0.5,0.5) {}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +Axis descriptions are \Tikz\ nodes, that means all placement and detail options of \cite{tikz} apply. The point on the node's boundary which is actually shifted to the |at| coordinate needs to be provided with an anchor (cf~\cite[Nodes and Edges]{tikz}): +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + legend entries={$x$,$x^2$}, + legend style={ + at={(1.03,0.5)}, + anchor=west + } + ] + \addplot {x}; + \addplot {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Standard anchors of nodes are |north|, |east|, |south|, |west| and mixed components like |north east|. + Please refer to \cite{tikz} for a complete documentation of anchors. + +\paragraph{Remarks:} +\begin{itemize} + \item Each of the anchors described in section~\ref{pgfplots:sec:align} can be described by |axis description cs| as well. + \item The |axis description cs| is independent of axis reversals or skewed axes. + Only for the default configuration of boxed axes is it the same as |rel axis cs|, i.e.\ |(0,0)| is the same as the smallest axis coordinate and |(1,1)| is the largest one in case of standard boxed axes\footnote{This was different in versions before 1.3: earlier versions did not have the distinction between \texttt{axis description cs} and \texttt{rel axis cs}.}. + + \item Even for three dimensional axes, the |axis description cs| is still two-dimensional: it always refers to coordinates relative to the tightest bounding box around the axis (without any descriptions or ticks). +\begin{codeexample}[width=4cm] +% the same as above for 3D ... +% [See the TikZ manual if you'd like to learn about nodes and pins] +\begin{tikzpicture} + \tikzset{ + every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny}, + small dot/.style={fill=black,circle,scale=0.3} + } + \begin{axis}[ + clip=false, + title=How \texttt{axis description cs} works in 3D + ] + \addplot3 coordinates {(-5,-5,-5) (5,5,5)}; + + \draw[black!15] (axis description cs:0,0) rectangle (axis description cs:1,1); + + \node[small dot,pin=120:{$(0,0)$}] at (axis description cs:0,0) {}; + \node[small dot,pin=-30:{$(1,1)$}] at (axis description cs:1,1) {}; + \node[small dot,pin=-90:{$(1.03,0.5)$}] at (axis description cs:1.03,0.5) {}; + \node[small dot,pin=125:{$(0.5,0.5)$}] at (axis description cs:0.5,0.5) {}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + \item Since the view does not influence these positions, |axis description cs| might not be a good choice for axis labels in 3D. The |ticklabel cs| is used in this case. +\end{itemize} +\end{coordinatesystem} + +\begin{coordinatesystemlist}{% + xticklabel cs,% + yticklabel cs,% + zticklabel cs, + ticklabel cs} + A set of special coordinate systems intended to place axis descriptions (or any other drawing operation) besides tick labels, in a way such that neither tick labels nor the axis as such are obscured. + + See also |xlabel near ticks| as one main application of |ticklabel cs|. + + The |xticklabel cs| (and its variants) always refer to one, uniquely identified axis: the one which is (or would be) annotated with tick labels. + + The |ticklabel cs| (without explicit \texttt{x}, \texttt{y} or \texttt{z}) can only be used in contexts where the axis character is known from context (for example, inside of |xlabel style| -- there, the |ticklabel cs| is equivalent to |xticklabel cs|). + + Each of these coordinate systems allows to specify points on a straight line which is placed parallel to an axis containing tick labels, moved away just far enough to avoid overlaps with the tick labels: +\begin{codeexample}[width=4cm] +\tikzset{ + every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny}, + small dot/.style={fill=black,circle,scale=0.3} +} +\begin{tikzpicture} +\begin{axis}[ + clip=false, + ticklabel style={draw=red}, + title=Positioning with \texttt{xticklabel cs}] + \addplot {x}; + \node[small dot,pin=-90:{\texttt{xticklabel cs:0}}] at (xticklabel cs:0) {}; + \node[small dot,pin=-90:{\texttt{xticklabel cs:0.5}}] at (xticklabel cs:0.5) {}; + \node[small dot,pin=-90:{\texttt{xticklabel cs:1}}] at (xticklabel cs:1) {}; + + + \node[small dot,pin=180:{\texttt{yticklabel cs:0}}] at (yticklabel cs:0) {}; + \node[small dot,pin=180:{\texttt{yticklabel cs:0.5}}] at (yticklabel cs:0.5) {}; + \node[small dot,pin=180:{\texttt{yticklabel cs:1}}] at (yticklabel cs:1) {}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +The basic idea is to place coordinates on a straight line which is parallel to the axis containing tick labels -- but shifted such that the line does not cut through tick labels. + +Of course, it is relatively simple to get the same coordinates as in the two dimensional example above with |axis description cs|, except that |ticklabel cs| always respects the tick label sizes appropriately. However, |ticklabel cs| becomes far superior when it comes to three dimensional positioning: + +\begin{codeexample}[width=4cm] +% the same as above for 3D ... +\begin{tikzpicture} + \tikzset{ + every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny}, + small dot/.style={fill=black,circle,scale=0.3} + } + \begin{axis}[ + ticklabel style={draw=red}, + clip=false, + title=Positioning with \texttt{ticklabel cs} in 3D + ] + \addplot3 coordinates {(-5,-5,-5) (5,5,5)}; + + \node[small dot,pin=-90:{\texttt{xticklabel cs:0}}] at (xticklabel cs:0) {}; + \node[small dot,pin=-90:{\texttt{xticklabel cs:0.5}}] at (xticklabel cs:0.5) {}; + \node[small dot,pin=-90:{\texttt{xticklabel cs:1}}] at (xticklabel cs:1) {}; + + \node[small dot,pin=-45:{\texttt{yticklabel cs:0}}] at (yticklabel cs:0) {}; + \node[small dot,pin=-45:{\texttt{yticklabel cs:0.5}}] at (yticklabel cs:0.5) {}; + \node[small dot,pin=-45:{\texttt{yticklabel cs:1}}] at (yticklabel cs:1) {}; + + \node[small dot,pin=180:{\texttt{zticklabel cs:0}}] at (zticklabel cs:0) {}; + \node[small dot,pin=180:{\texttt{zticklabel cs:0.5}}] at (zticklabel cs:0.5) {}; + \node[small dot,pin=180:{\texttt{zticklabel cs:1}}] at (zticklabel cs:1) {}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The coordinate |ticklabel cs:0| is associated to the lower axis limit while |ticklabel cs:1| is near the upper axis limit. The value |0.5| is in the middle of the axis, any other values (including negative values or values beyond $1$) are linearly interpolated inbetween. + + The |ticklabel cs| also accepts a second (optional) argument: a shift ``away'' from the tick labels. The shift points to a vector which is orthogonal to the associated axis, away from the tick labels. A shift of |0pt| is directly at the edge of the tick labels in direction of the normal vector, positive values move the position away and negative closer to the tick labels. +\begin{codeexample}[width=4cm] +\tikzset{ + every pin/.style={fill=yellow!50!white,rectangle,rounded corners=3pt,font=\tiny}, + small dot/.style={fill=black,circle,scale=0.3} +} +\begin{tikzpicture} + \begin{axis}[ + xticklabel style={draw=red}, + clip=false, + title=\texttt{ticklabel cs} and its optional shift + ] + \addplot3 coordinates {(-5,-5,-5) (5,5,5)}; + + \draw[blue,thick,->] (xticklabel cs:0,0) -- (xticklabel cs:1,0); + \draw[red,thick,->] (xticklabel cs:0,5pt) -- (xticklabel cs:1,5pt); + \draw[magenta,thick,->] (xticklabel cs:0,10pt) -- (xticklabel cs:1,10pt); + \draw[green,thick,->] (xticklabel cs:0,15pt) -- (xticklabel cs:1,15pt); + \node[small dot,pin=0:{\texttt{xticklabel cs:1,0}}] at (xticklabel cs:1,0) {}; + \node[small dot,pin=0:{\texttt{xticklabel cs:1,15pt}}] at (xticklabel cs:1,15pt) {}; + + \draw[blue,thick,->] (xticklabel cs:0,0) -- (xticklabel cs:0,15pt); + \draw[blue,thick,->] (xticklabel cs:1,0) -- (xticklabel cs:1,15pt); + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Whenever the |ticklabel cs| is used, the anchor should be set to |anchor=near ticklabel| (see below). + + There is one speciality: if you reverse an axis (with |x dir=reverse|), points provided by |ticklabel cs| will be \emph{unaffected} by the axis reversal. This is intented to provide consistent placement even for reversed axes. Use |allow reversal of rel axis cs=false| to disable this feature. +\end{coordinatesystemlist} + + +Besides the mentioned positioning methods, there is also the predefined node |current axis|. The anchors of |current axis| can also be used to place descriptions: At the time when axis descriptions are drawn, all anchors which refer to the axis origin (that means the ``real'' point $(0,0)$) or any of the axis corners can be referenced using |current axis.|\meta{anchor name}. Please see section~\ref{pgfplots:sec:align}, Alignment, for further details. + +\subsubsection{Alignment of Axis Descriptions} +This section describes how to modify the default alignment of axis descriptions. It can be skipped at first reading. + +The two topics positioning and alignment always work together: \emph{positioning} means to select an appropriate coordinate and \emph{alignment} means to select an anchor inside of the description which will actually be moved to the desired position. + +\Tikz\ uses many anchors to provide alignment; most of them are named like |north|, |north east| etc. These names hold for any axis description as well (as axis description are \Tikz\ nodes). Readers can learn details about this topic in the \Tikz\ manual~\cite{tikz} or some more advice in section~\ref{pgfplots:sec:align}. + +When it comes to axis descriptions, \PGFPlots\ offers some specialized anchors and alignment methods which are described below. +\begin{anchorlist}{near xticklabel,near yticklabel,near zticklabel,near ticklabel} + These anchors can be used to align at the part of a node (for example, an axis description) which is \emph{nearest} to the tick labels of a particular axis (or nearest to the position where tick labels would have been drawn if there were any). + + These anchors are used for axis labels, especially for three dimensional axes. Furthermore, they are used for every tick label. + +\label{key:near:ticklabel} + Maybe it is best to demonstrate it by example: +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + title=Without \texttt{near ticklabel}, + ylabel={$f(x)=x$}, + every axis y label/.style= + {at={(ticklabel cs:0.5)},rotate=90,anchor=center}, + clip=false,% to display the \path below + ylabel style={draw=red}, + yticklabel style={draw=red} + ] + + \addplot {x}; + + % visualize the position: + \fill (yticklabel cs:0.5) circle(2pt); + \end{axis} +\end{tikzpicture}% +~ +\begin{tikzpicture} + \begin{axis}[ + title=With \texttt{near ticklabel}, + ylabel={$f(x)=x$}, + every axis y label/.style= + {at={(ticklabel cs:0.5)},rotate=90,anchor=near ticklabel}, + clip=false, + ylabel style={draw=red}, + yticklabel style={draw=red} + ] + + \addplot {x}; + \fill (yticklabel cs:0.5) circle(2pt); + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The motivation is to place nodes such that they are anchored next to the tick label, regardless of the node's rotation or the position of ticks. The special anchor |near ticklabel| is only available for axis labels (as they have a uniquely identified axis, either $x$, $y$ or $z$). + + In more detail, the anchor is placed such that first, the node's center is on a line starting in the node's |at| position going in direction of the inwards normal vector of the axis line which contains the tick labels and second, the node does not intrude the axis. This normal vector is the same which is used for the shift argument in |ticklabel cs|: it is orthogonal to the tick label axis. Furthermore, |near ticklabel| inverts the transformation matrix before it computes this intersection point. + + The |near ticklabel| anchor and its friends will be added temporarily to any shape used inside of an axis. This includes axis description, but it is not limited to them: it applies to every \Tikz\ |\node[anchor=near xticklabel] ...| setting. + + Note that it is not necessary at all to \emph{have} tick labels in an axis. The anchor will be placed such that it is near the axis on which tick labels \emph{would} be drawn. In fact, every tick label uses |anchor=near ticklabel| as initial configuration. +\end{anchorlist} + +\begin{pgfplotsxykeylist}{/tikz/sloped like \x\space axis} + A key which replaces the rotational / scaling parts of the transformation matrix such that the node is sloped like the provided axis. For two dimensional plots, |sloped like y axis| is effectively the same as |rotate=90|. For a three dimensional axis, this will lead to a larger difference: +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + xlabel=Variable 1, + ylabel=Variable 2, + zlabel=value, + xlabel style={sloped like x axis}, + ylabel style={sloped} + ] + + \addplot3[surf] {y*x*(1-x)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Inside of axis labels, |sloped| is an alias |sloped like |\meta{char}| axis| with the correct \meta{char} chosen automatically. + + Please note that rotated text might not look very good (neither on screen nor printed). +\end{pgfplotsxykeylist} + + +\subsubsection{Labels} + +\begin{pgfplotsxykey}{\x label=\marg{text}} +These options set axis labels to \marg{text} which is any \TeX\ text. Use curly braces to include special characters, for example ``|xlabel={, = characters}|'' if characters like `|=|' or `|,|' need to be included literally. + + Use |xlabel/.add=|\marg{prefix}\marg{suffix} to modify an already assigned label. + +Labels are \Tikz-Nodes which are placed with +\begin{codeexample}[code only] +% for x: +\node + [style=every axis label, + style=every axis x label] + +% for y: +\node + [style=every axis label, + style=every axis y label] +\end{codeexample} +so their position and appearance can be customized. + +\paragraph{Upgrade notice:} Since version 1.3, label placement \emph{can} respect the size of adjacent tick labels. Use |\pgfplotsset{compat=newest}| in the preamble to activate this feature. See |xlabel near ticks| for details. + +\begin{pgfplotsxykeylist}{\x label shift=\marg{dimension} (initially 0pt),label shift=\marg{dimension}} + Shifts labels in direction of the outer normal vector of the axis by an amount of \marg{dimension}. The |label shift| sets all three label shifts to the same value. + + \paragraph{Attention:} This does only work if |\pgfplotsset{compat=newest}| has been called (More precisely: if |xlabel near ticks| is active for the respective axis). +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykeylist}{\x label near ticks,compat=newest} + These keys place axis labels (like |xlabel|) near the tick labels. If tick labels are small, labels will move closer to the axis. If tick labels are large, axis labels will move away from the axis. This is the default for every three dimensional plot, but it \emph{won't} be used initially for two--dimensional plots for backwards compatibility. Take a look at the definition of |near ticklabel| on page~\pageref{key:near:ticklabel} for an example. + + The definition of these styles is +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/xlabel near ticks/.style={ + /pgfplots/every axis x label/.style={ + at={(ticklabel cs:0.5)},anchor=near ticklabel + } + }, + /pgfplots/ylabel near ticks/.style={ + /pgfplots/every axis y label/.style={ + at={(ticklabel cs:0.5)},rotate=90,anchor=near ticklabel + } + } +} +\end{codeexample} + + It is encouraged to write +\begin{codeexample}[code only] +\pgfplotsset{compat=newest} +\end{codeexample} + \noindent in your preamble to install the styles document-wide -- it leads to the best output (it avoids unnecessary space). It is not activated initially for backwards compatibility with older versions which used fixed distances from the tick labels. +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykeylist}{\x label absolute,compat=pre 1.3} + Installs placement styles for axis labels such that |xlabel| yields a description of absolute, fixed distance to the axis. This is the initial configuration (for backwards compatibility with versions before 1.3). Use |compat=newest| to get the most recent, more flexible configuration. Take a look at the definition of |near ticklabel| on page~\pageref{key:near:ticklabel} for an example. + + These styles are defined by +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/xlabel absolute/.style={% + /pgfplots/every axis x label/.style={at={(0.5,0)},below,yshift=-15pt},% + /pgfplots/every x tick scale label/.style={ + at={(1,0)},yshift=-2em,left,inner sep=0pt + }, + }, + /pgfplots/ylabel absolute/.style={% + /pgfplots/every axis y label/.style={at={(0,0.5)},xshift=-35pt,rotate=90}, + /pgfplots/every y tick scale label/.style={ + at={(0,1)},above right,inner sep=0pt,yshift=0.3em + }, + } +} +\end{codeexample} + + There is no predefined absolute placement style for three dimensional axes. +\end{pgfplotsxykeylist} + +Whenever possible, consider using |/.append style| instead of overwriting the default styles to ensure compatibility with future versions. +\begin{codeexample}[code only] +\pgfplotsset{every axis label/.append style={...}} +\pgfplotsset{every axis x label/.append style={...}} +\pgfplotsset{every axis y label/.append style={...}} +\end{codeexample} +\end{pgfplotsxykey} + +\begin{pgfplotskey}{title=\marg{text}} +Adds a caption to the plot. This will place a \Tikz-Node with +\begin{codeexample}[code only] +\node[every axis title] {text}; +\end{codeexample} +to the current axis. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{loglogaxis}[ + xlabel=Dof,ylabel=Error, + title={$\mu=0.1$, $\sigma=0.2$}] + + \addplot coordinates { + (5, 8.312e-02) + (17, 2.547e-02) + (49, 7.407e-03) + (129, 2.102e-03) + (321, 5.874e-04) + (769, 1.623e-04) + (1793, 4.442e-05) + (4097, 1.207e-05) + (9217, 3.261e-06) + }; +\end{loglogaxis} +\end{tikzpicture}% +\end{codeexample} +%-------------------------------------------------- +% \hfill +% \begin{tikzpicture} +% \begin{loglogaxis}[ +% width=0.48\linewidth, +% xlabel=Dof,ylabel=Error, +% title={$\mu=1$, $\sigma=\frac{1}{2}$}] +% +% \addplot[color=red,mark=*] coordinates { +% (7, 8.472e-02) +% (31, 3.044e-02) +% (111, 1.022e-02) +% (351, 3.303e-03) +% (1023, 1.039e-03) +% (2815, 3.196e-04) +% (7423, 9.658e-05) +% (18943, 2.873e-05) +% (47103, 8.437e-06) +% }; +% \end{loglogaxis} +% \end{tikzpicture} +%-------------------------------------------------- +The title's appearance and/or placing can be reconfigured with +\begin{codeexample}[code only] +\pgfplotsset{title style={at={(0.75,1)}}} +% or, equivalently, +\pgfplotsset{every axis title/.append style={at={(0.75,1)}}} +\end{codeexample} +This will place the title at~75\% of the $x$-axis. The coordinate~$(0,0)$ is the lower left corner and~$(1,1)$ the upper right one (see |axis description cs| for details). + +Use |title/.add=|\marg{prefix}\marg{suffix} to modify an already assigned title. +\end{pgfplotskey} + +\begin{pgfplotscodekey}{extra description} +Allows to insert \marg{commands} after axis labels, titles and legends have been typeset. + +As all other axis descriptions, the code can use $(0,0)$ to access the lower left corner and $(1,1)$ to access the upper right one. It won't be clipped. +\begin{codeexample}[] +\pgfplotsset{every axis/.append style={ + extra description/.code={ + \node at (0.5,0.5) {Center!}; + }}} +\begin{tikzpicture} + \begin{axis} + \addplot {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotscodekey} + + +\subsubsection{Legends} +\label{pgfplots:sec:legendopts} +\label{pgfplots:sec:legendcmds} +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}} +Adds a single legend entry to the legend list. This will also enable legend drawing. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot[smooth,mark=*,blue] coordinates { + (0,2) + (2,3) + (3,1) +}; +\addlegendentry{Case 1} + +\addplot[smooth,color=red,mark=x] + coordinates { + (0,0) + (1,1) + (2,1) + (3,2) + }; +\addlegendentry{Case 2} +\end{axis} +\end{tikzpicture} +\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). + + +Using |\addlegendentry| disables the key |legend entries|. +\end{command} + +\begin{command}{\addlegendentryexpanded\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|: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \foreach \p in {1,2,3} { + \addplot {x^\p}; + \addlegendentryexpanded{$x^\p$} + } +\end{axis} +\end{tikzpicture} +\end{codeexample} + Note that this example wouldn't have worked with |\addlegendentry{$x^\p$}| because the macro |\p| is no longer defined when \PGFPlots\ attempts to draw the legend. + + The invocation |\addlegendentryexpanded{$x^\p$}| is equivalent to calling |\addlegendentry{$x^2$}| if |\p| expands to |2|. + + The argument \meta{\TeX\ text} is expanded until nothing but un-expandable material remains (i.e.\ it uses the \TeX\ primitive |\edef|). Occasionally, \marg{\TeX\ text} contains parts which should be expanded (like |\p|) and other parts which should be left unexpanded (for example |\pgfmathprintnumber{\p}|). Then, use + + |\noexpand\pgfmathprintnumber{\p}| + + or, equivalently + + |\protect\pgfmathprintnumber{\p}| + + to avoid expansion of the macro which follows the |\protect| immediately. +\end{command} + + + +\begin{command}{\legend\marg{list}} +\label{sec:legenddef}% +You can use |\legend|\marg{list} to assign a complete legend. +\begin{codeexample}[code only] +\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} +\end{codeexample} +The argument of |\legend| is list of entries, one for each plot. + +Two different delimiters are supported: +\begin{enumerate} + \item There are comma--separated lists like +\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. + \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. +\end{enumerate} +The short marker/line combination shown in legends is acquired from the \marg{style options} argument of |\addplot|. + +Using |\legend| overwrites any other existing legend entries. +\end{command} + + +\begin{pgfplotskey}{legend entries=\marg{comma separated list}} + This key can be used to assign legend entries just like the commands |\addlegendentry| and |\legend|. Again, the positioning is relative to the axis rectangle (unless units like |cm| or |pt| are specified explicitly). +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[legend entries={$x$,$x^2$}] + \addplot {x}; + \addplot {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The commands for legend creation take precedence: the key |legend entries| is only considered if there is no legend command in the current axis. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[legend entries={$x$,$x^2$}] + \addplot {x}; + \addplot {x^2}; + \legend{$a$,$b$}% overrides the option + \end{axis} +\end{tikzpicture} +\end{codeexample} + Please be careful with whitespaces in \marg{comma separated list}: they will contribute to legend entries. Consider using `|%|' at the end of each line in multiline arguments (the end of line character is also a whitespace in \TeX). +\end{pgfplotskey} + + +\begin{command}{\legendimage\marg{options}} + Adds a further ``plot style'' for legend creation. + + Each |\addplot| command appends its plot style options to a list, and |\legendimage| adds \meta{options} to the very same list. + + Thus, the effect is as if you had provided |\addplot|\oarg{options}, but |\legendimage| 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. + + Use |\legendimage| to provide custom styles into legends, for example to document custom |\draw| commands inside of an axis. + + You can call |\label| after |\legendimage| just as for a normal style. +\end{command} + +\subsubsection{Legend Appearance} + +{% +\pgfplotsset{every axis/.append style={width=3cm,scale only axis,legend style={font=\footnotesize}}}% + + +\begin{stylekey}{/pgfplots/every axis legend} +The style ``|every axis legend|'' determines the legend's position and outer appearance: +\begin{codeexample}[code only] +\pgfplotsset{every axis legend/.append style={ + at={(0,0)}, + anchor=south west}} +\end{codeexample} +will draw it at the lower left corner of the axis while +\begin{codeexample}[code only] +\pgfplotsset{every axis legend/.append style={ + at={(1,1)}, + anchor=north east}} +\end{codeexample} +means the upper right corner. The `|anchor|' option determines which point \emph{of the legend} will be placed at $(0,0)$ or $(1,1)$. + +The legend is a \Tikz-matrix, so one can use any \Tikz\ option which affects +nodes and matrizes (see~\cite[section 13~and~14]{tikz}). The matrix is created by something like +\begin{codeexample}[code only] +\matrix[style=every axis legend] { + draw plot specification 1 & \node{legend 1}\\ + draw plot specification 2 & \node{legend 2}\\ + ... +}; +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + % this modifies 'every axis legend': + legend style={font=\large} +] +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$,$l_2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + % align right: + legend style={ + cells={anchor=east}, + legend pos=outer north east, + } +] +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$, legend $2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +% similar placement as previous example: +\pgfplotsset{every axis legend/.append style={ + at={(1.02,1)}, + anchor=north west}} +\begin{tikzpicture} +\begin{axis} +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$,$l_2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +Use |legend columns=|\marg{number} to configure the number of horizontal legend entries. +\begin{codeexample}[] +\begin{tikzpicture} +\pgfplotsset{every axis legend/.append style={ + at={(0.5,1.03)}, + anchor=south}} +\begin{axis}[legend columns=4] +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$,$l_2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent +Instead of the |/.append style|, it is possible to use |legend style| as in the following example. It has the same effect. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + legend style={ + at={(1,0.5)}, + anchor=east}] +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$,$l_2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\noindent +The default |every axis legend| style is +\begin{codeexample}[code only] +\pgfplotsset{every axis legend/.style={ + cells={anchor=center},% Centered entries + inner xsep=3pt,inner ysep=2pt,nodes={inner sep=2pt,text depth=0.15em}, + anchor=north east, + shape=rectangle, + fill=white, + draw=black, + at={(0.98,0.98)} + } +} +\end{codeexample} +Whenever possible, consider using |/.append style| to keep the default styles active. This ensures compatibility with future versions. +\begin{codeexample}[code only] +\pgfplotsset{every axis legend/.append style={...}} +\end{codeexample} +\end{stylekey} + +\pgfplotsshortstylekey legend style=every axis legend\pgfeov + + +\begin{pgfplotskey}{legend pos=\mchoice{south west,south east,north west,north east,outer north east}} + A style which provides shorthand access to some commonly used legend positions. + + Each of these styles appends |at={(|\meta{x}|,|\meta{y}|)},anchor=|\meta{name} values to |every axis legend|. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[legend pos=south west] +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$,$l_2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[legend pos=south east] +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$,$l_2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[legend pos=north east] +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$,$l_2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[legend pos=north west] +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$,$l_2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[legend pos=outer north east] +\addplot coordinates {(0,0) (1,1)}; +\addplot coordinates {(0,1) (1,2)}; +\addplot coordinates {(0,2) (1,3)}; +\legend{$l_1$,$l_2$,$l_3$} +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + +} + +\begin{pgfplotskey}{legend columns=\marg{number} (default 1)} +Allows to configure the maximum number of adjacent legend entries. The default value~|1| places legend entries vertically below each other. + +Use |legend columns=-1| to draw all entries horizontally. +\end{pgfplotskey} + +\begin{pgfplotskey}{legend plot pos=\mchoice{left,right,none} (initially left)} +Configures where the small line specifications will be drawn: left of the description, right of the description or not at all. +\end{pgfplotskey} + +\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. + + +The default is the style |line legend|. +\end{pgfplotscodekey} + +\begin{stylekey}{/pgfplots/line legend} + A style which sets |legend image code| (back) to its initial value. + + Its initial value is +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/line legend/.style={ + legend image code/.code={ + \draw[mark repeat=2,mark phase=2,##1] + plot coordinates { + (0cm,0cm) + (0.3cm,0cm) + (0.6cm,0cm) + };% + } + } +} +\end{codeexample} + + 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/area legend} + A style which sets |legend image code| to +\begin{codeexample}[code only] +\pgfplotsset{ + legend image code/.code={% + \draw[#1] (0cm,-0.1cm) rectangle (0.6cm,0.1cm); + } +} +\end{codeexample} + +% \usetikzlibrary{patterns} +\begin{codeexample}[] +% \usetikzlibrary{patterns} +\begin{tikzpicture} +\begin{axis}[area legend, + axis x line=bottom, + axis y line=left, + domain=0:1, + legend style={at={(0.03,0.97)}, + anchor=north west}, + axis on top,xmin=0] +\addplot[pattern=crosshatch dots, + pattern color=blue,draw=blue, + samples=500] + {sqrt(x)} \closedcycle; + +\addplot[pattern=crosshatch, + pattern color=blue!30!white, + draw=blue!30!white] + {x^2} \closedcycle; + +\addplot[red,line legend] coordinates {(0,0) (1,1)}; +\legend{$\sqrt x$,$x^2$,$x$} +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{stylekey} + +\begin{pgfplotsxykeylist}{\x bar legend,\x bar interval legend} + These style keys redefine |legend image code| such that legends use |xbar|, |ybar| or the |xbar interval| and |ybar interval| handlers. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[legend pos=north west] + \addplot {x^3}; + \addplot[ybar,fill=red,draw=red!60, + ybar legend,mark=none,samples=5] + {-30*(x +4)}; + \legend{first,second} + \end{axis} +\end{tikzpicture} +\end{codeexample} +The initial values for these styles might be interesting if someone wants to modify them. Here are they: +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/xbar legend/.style={ + /pgfplots/legend image code/.code={% + \draw[##1,/tikz/.cd,bar width=3pt,yshift=-0.2em,bar shift=0pt] + plot coordinates {(0cm,0.8em) (2*\pgfplotbarwidth,0.6em)};}, + }, + /pgfplots/ybar legend/.style={ + /pgfplots/legend image code/.code={% + \draw[##1,/tikz/.cd,bar width=3pt,yshift=-0.2em,bar shift=0pt] + plot coordinates {(0cm,0.8em) (2*\pgfplotbarwidth,0.6em)};}, + }, + /pgfplots/xbar interval legend/.style={% + /pgfplots/legend image code/.code={% + \draw[##1,/tikz/.cd,yshift=-0.2em,bar interval width=0.7,bar interval shift=0.5] + plot coordinates {(0cm,0.8em) (5pt,0.6em) (10pt,0.6em)};}, + }, + /pgfplots/ybar interval legend/.style={ + /pgfplots/legend image code/.code={% + \draw[##1,/tikz/.cd,yshift=-0.2em,bar interval width=0.7,bar interval shift=0.5] + plot coordinates {(0cm,0.8em) (5pt,0.6em) (10pt,0.6em)};}, + }, +} +\end{codeexample} +\end{pgfplotsxykeylist} + +\begin{pgfplotskey}{mesh legend} + Redefines |legend image code| such that it is compatible with |mesh| and |surf| plot handlers (for three dimensional visualization mainly). +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[legend pos=outer north east] + \addplot3[surf,samples=9,domain=0:1] + {(1-abs(2*(x-0.5))) * (1-abs(2*(y-0.5)))}; + \addlegendentry{$\phi_x \phi_y$} + + \addplot3+[ultra thick] coordinates {(0,0,0) (0.5,0,1) (1,0,0)}; + \addlegendentry{$\phi_x $} + + \addplot3+[ultra thick] coordinates {(1,0,0) (1,0.5,1) (1,1,0)}; + \addlegendentry{$\phi_y $} + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + +\begin{pgfplotskey}{reverse legend=\mchoice{true,false} (initially false)} + Allows to reverse the order in which the pairs (legend entry, plot style) are drawn. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[reverse legend] + \addplot {x}; + \addlegendentry{$x$} + \addplot {x^2}; + \addlegendentry{$x^2$} + \addplot {x^3}; + \addlegendentry{$x^3$} + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + + +\subsubsection{Legends with \texttt{\textbackslash label} and \texttt{\textbackslash ref}} +\label{pgfplots:legend:labelref} +\PGFPlots\ offers a |\label| and |\ref| feature for \LaTeX\ to assemble a legend manually, for example as part of the figure caption. These references work as usual \LaTeX\ references: a |\label| remembers where and what needs to be referenced and a |\ref| expands to proper text. In context of plots, a |\label| remembers the plot specification of one plot and a |\ref| expands to the small image which would also be used inside of legends. +\begin{codeexample}[] +\begin{tikzpicture}[baseline] +\begin{axis} + \addplot+[only marks, + samples=15, + error bars/y dir=both, + error bars/y fixed=2.5] + {3*x+2.5*rand}; + \label{pgfplots:label1} + + \addplot+[mark=none] {3*x}; + \label{pgfplots:label2} + + \addplot {4*cos(deg(x))}; + \label{pgfplots:label3} +\end{axis} +\end{tikzpicture} +\end{codeexample} +\begin{codeexample}[code only] +The picture shows the estimations \ref{pgfplots:label1} which are subjected to noise. +It appears the model \ref{pgfplots:label2} fits the data appropriately. +Finally, \ref{pgfplots:label3} is only here to get three examples. +\end{codeexample} +\noindent The picture shows the estimations \ref{pgfplots:label1} which are subjected to noise. +It appears the model \ref{pgfplots:label2} fits the data appropriately. +Finally, \ref{pgfplots:label3} is only here to get three examples. + +\begin{commandlist}{\label\marg{label name},\label\oarg{reference}\marg{label name}} + When used after |\addplot|, this command creates a \LaTeX\ label named \marg{label name}\footnote{This feature is \emph{only} available in \LaTeX, sorry.}. If this label is cross-referenced with |\ref|\marg{label name} somewhere, the associated plot specification will be inserted. +\begin{codeexample}[] +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 independant 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.}. + + More precisely, the small image generated by |\ref|\marg{label name} is +\begin{codeexample}[code only] +\tikz[/pgfplots/every crossref picture] {...} +\end{codeexample} + \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. +\end{commandlist} + +\begin{command}{\ref\marg{label name}} + Can be used to reference a labeled, single plot. See the example above. + + This will also work together with |hyperref| links and |\pageref|\footnote{Older versions of \PGFPlots\ required the use of \texttt{\textbackslash protect\textbackslash ref} when used inside of captions or section headings. This is no longer necessary.}. +\end{command} + +\begin{key}{/pgfplots/refstyle=\marg{label name}} + Can be used to set the \emph{styles} of a labeled, single plot. This allows to write +\begin{codeexample}[code only] +\addplot[/pgfplots/refstyle={pgfplots:label2}] +\end{codeexample} + \noindent somewhere. Please note that it may be easier to define a style with |.style|. +\end{key} + +\begin{stylekey}{/pgfplots/every crossref picture} + A style which will be used by the cross-referencing feature for plots. The default is +\begin{codeexample}[code only] +\pgfplotsset{every crossref picture/.style={baseline,yshift=0.3em}} +\end{codeexample} +\end{stylekey} + +\subsubsection{Axis Lines} + +{\small \emph{An extension by Pascal Wolkotte}} +\vspace{0.4cm}% + +\label{sec:pgfplots:axislines} +\noindent By default the axis lines are drawn as a |box|, but it is possible to change the appearance of the $x$~and~$y$ axis lines. + +\begin{pgfplotskeylist}{ + axis x line=\mchoice{box,top,middle,center,bottom,none} (initially box), + axis x line*=\mchoice{box,top,middle,center,bottom,none} (initially box), + axis y line=\mchoice{box,left,middle,center,right,none} (initially box), + axis y line*=\mchoice{box,left,middle,center,right,none} (initially box), + axis lines=\mchoice{box,left,middle,center,right,none}, + axis lines*=\mchoice{box,left,middle,center,right,none}} + These keys allow to choose the locations of the axis lines. The last one, |axis lines| sets the same value for every axis. + +Ticks and tick labels are placed according to the chosen value as well. +The choice |bottom| will draw the $x$ line at $y=y_\text{min}$, |middle| will draw the $x$~line at $y=0$, and |top| will draw it at $y=y_\text{max}$. Finally, |box| is a combination of options |top| and |bottom|. The $y$~variant works similarly. + +The case |center| is a synonym for |middle|, both draw the line through the respective coordinate~$0$. If this coordinate is not part of the axis limit, the lower axis limit is chosen instead. + + +The starred versions $\dotsc$|line*| \emph{only} affect the axis lines, without correcting the positions of axis labels, tick lines or other keys which are (possibly) affected by a changed axis line. The non-starred versions are actually styles which set the starred key \emph{and} some other keys which also affect the figure layout: +\begin{itemize} + \item In case |axis x line=box|, the style |every boxed x axis| will be installed immediately. + \item In case |axis x line|$\neq$|box|, the style |every non boxed x axis| will be installed immediately. Furthermore, axis labels positions will be adjusted to fit the choosen value. +\end{itemize} +The same holds true for the |y|-variants. The default styles are defined as +\begin{codeexample}[code only] +\pgfplotsset{ + every non boxed x axis/.style={ + xtick align=center, + enlarge x limits=false, + x axis line style={-stealth} + }, + every boxed x axis/.style={} +} +\end{codeexample} +Feel free to overwrite these styles if the default doesn't fit your needs or taste. Again, these styles will \emph{not} be used for |axis line*|. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xlabel=$x$,ylabel=$\sin x$] + + \addplot[blue,mark=none, + domain=-10:0,samples=40] + {sin(deg(x))}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + axis x line=middle, + axis y line=right, + ymax=1.1, ymin=-1.1, + xlabel=$x$,ylabel=$\sin x$ +] + \addplot[blue,mark=none, + domain=-10:0,samples=40] + {sin(deg(x))}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + axis x line=bottom, + axis y line=left, + xlabel=$x$,ylabel=$\sqrt{|x|}$ +] +\addplot[blue,mark=none, + domain=-4:4,samples=501] + {sqrt(abs(x))}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + minor tick num=3, + axis y line=center, + axis x line=middle, + xlabel=$x$,ylabel=$\sin x$ + ] + \addplot[smooth,blue,mark=none, + domain=-5:5,samples=40] + {sin(deg(x))}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + minor tick num=3, + axis y line=left, + axis x line=middle, + xlabel=$x$,ylabel=$\sin x$ + ] + \addplot[smooth,blue,mark=none, + domain=-5:5,samples=40] + {sin(deg(x))}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +In case |middle|, the style |every inner axis x line| allows to adjust the appearenace. + +Note that three dimensional axes only support to use the same value for every axis, i.e.\ three dimensional axes support only the |axis lines| key (or, preferrably for 3D axes, the |axis lines*| key -- check what looks best). See section~\ref{sec:pgfplots:axislines:3d} for examples of three dimensional axis line variations. +\end{pgfplotskeylist} + +\begin{pgfplotsxykey}{every inner \x\ axis line} + A style key which can be redefined to customize the appearance of \emph{inner} axis lines. Inner axis lines are those drawn by the |middle| (or |center|) choice of |axis x line|, see above. + + This style affects \emph{only} the line as such. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + minor tick num=1, + axis x line=middle, + axis y line=middle, + every inner x axis line/.append style= + {|->>}, + every inner y axis line/.append style= + {|->>}, + xlabel=$x$,ylabel=$y^3$ +] +\addplot[blue,domain=-3:5] {x^3}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{every outer \x\ axis line} + Similar to |every inner x axis line|, this style configures the appearance of all axis lines which are part of the outer box. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + separate axis lines, % important ! + every outer x axis line/.append style= + {-stealth}, + every outer y axis line/.append style= + {-stealth}, +] +\addplot[blue,id=DoG, + samples=100, + domain=-15:15] + gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykey} + +\begin{pgfplotskey}{separate axis lines=\marg{true,false} (default true)} + Enables or disables separate path commands for every axis line. This option affects \emph{only} the case if axis lines are drawn as a \emph{box}. + + Both cases have their advantages and disadvantages, I fear there is no reasonable default (suggestions are welcome). + + The case |separate axis lines=true| allows to draw arrow heads on each single axis line, but it can't close edges very well -- in case of thick lines, unsatisfactory edges occur. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + separate axis lines, + every outer x axis line/.append style= + {-stealth,red}, + every outer y axis line/.append style= + {-stealth,green!30!black}, +] +\addplot[blue, + samples=100, + domain=-15:15] + {1.3*exp(0-x^2/10) - exp(0-x^2/20)}; + % Unfortunately, there is a bug in PGF 2.00 + % something like exp(-10^2) + % must be written as exp(0-10^2) :-( +\end{axis} +\end{tikzpicture} +\end{codeexample} + + The case |separate axis lines=false| issues just \emph{one} path for all axis lines. It draws a kind of rectangle, where some parts of the rectangle may be skipped over if they are not wanted. The advantage is that edges are closed properly. The disadvantage is that at most one arrow head is added to the path (and yes, only one drawing color is possible). +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + separate axis lines=false, + every outer x axis line/.append style= + {-stealth,red}, + every outer y axis line/.append style= + {-stealth,green!30!black}, +] +\addplot[blue,id=DoG, + samples=100, + domain=-15:15] + gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + + +\label{pgfplots:page:axislines} +\begin{pgfplotskey}{axis line style=\marg{key-value-list}} + A command which appends \marg{key-value-list} to \emph{all} axis line appearance styles. +\end{pgfplotskey} + +\begin{pgfplotskey}{inner axis line style=\marg{key-value-list}} + A command which appends \marg{key-value-list} to both, |every inner x axis line| and the $y$ variant. +\end{pgfplotskey} +\begin{pgfplotskey}{outer axis line style=\marg{key-value-list}} + A command which appends \marg{key-value-list} to both, |every outer x axis line| and the $y$ variant. +\end{pgfplotskey} +\begin{pgfplotsxykey}{\x\ axis line style=\marg{key-value-list}} + A command which appends \marg{key-value-list} to all axis lines styles for either $x$ or $y$ axis. +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{every boxed \x\ axis} + A style which will be installed as soon as |axis x line=box| (|y|) is set. + + The default is simply empty. +\end{pgfplotsxykey} +\begin{pgfplotsxykey}{every non boxed \x\ axis} + A style which will be installed as soon as |axis x line| (|y|) will be set to something different than |box|. + + The default is +\begin{codeexample}[code only] +\pgfplotsset{ + every non boxed x axis/.style={ + xtick align=center, + enlarge x limits=false, + x axis line style={-stealth}}} +\end{codeexample} + \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)} +{% +\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. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + scale only axis, + xmin=-5,xmax=5, + axis y line=left, + xlabel=$x$, + ylabel=First ordinate] + \addplot {x^2}; + \end{axis} + + \begin{axis}[ + scale only axis, + xmin=-5,xmax=5, + 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: +\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. +\end{enumerate} +You may want to consider different legend styles. +It is also possible to use only the axis, without any plots: +% \usepackage{textcomp} +\begin{codeexample}[] +% \usepackage{textcomp} +\begin{tikzpicture} + \begin{axis}[ + scale only axis, + xmin=-5,xmax=5, + axis y line=left, + xlabel=$x$, + ylabel=Absolute] + \addplot {x^2}; + \end{axis} + + \begin{axis}[ + scale only axis, + xmin=-5,xmax=5, + ymin=0,ymax=1000, + yticklabel= +{$\pgfmathprintnumber{\tick}$\textperthousand}, + axis y line=right, + axis x line=none, + y label style={yshift=-10pt}, + ylabel=per thousand] + \end{axis} +\end{tikzpicture} +\end{codeexample} +} + +\subsubsection{Axis Discontinuities} + +{\small \emph{An extension by Pascal Wolkotte}} +\vspace{0.4cm}% + +\noindent In case the range of either of the axis do not include the zero value, it is possible to visualize this with a discontinuity decoration on the corresponding axis line. + +\begin{pgfplotsxykey}{axis \x\ discontinuity=\mchoice{crunch,parallel,none} (initially none)} +Insert a discontinuity decoration on the $x$ (or $y$, respectively) axis. +This is to visualize that the $y$ axis does cross the $x$ axis at its $0$ value, because the minimum $x$ axis value is positive or the maximum value is negative. + +The description applies |axis y discontinuity| as well, with interchanged meanings of $x$~and~$y$. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + axis x line=bottom, + axis x discontinuity=parallel, + axis y line=left, + xmin=360, xmax=600, + ymin=0, ymax=7, + enlargelimits=false +] + \addplot coordinates { + (420,2) + (500,6) + (590,4) + }; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + axis x line=bottom, + axis y line=center, + tick align=outside, + axis y discontinuity=crunch, + ymin=95, enlargelimits=false +] + \addplot[blue,mark=none, + domain=-4:4,samples=20] + {x*x+x+104}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykey} + +A problem might occur with the placement of the ticks on the axis. +This can be solved by specifying the minimum or maximum axis value for which a tick will be placed. + +\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord} (default axis limits), \x tickmax=\marg{coord} (default axis limits)} +\label{key:xytickminmax} +The options |xtickmin|, |xtickmax| and |ytickmin|, |ytickmax| allow to define the axis tick limits, i.e.\ the axis values before respectively after no ticks will be placed. +Everything outside of the axis tick limits will be not drawn. +Their default values are equal to the axis limits. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + axis x line=bottom, + axis y line=center, + tick align=outside, + axis y discontinuity=crunch, + xtickmax=3, + ytickmin=110, + ymin=95, enlargelimits=false +] + \addplot[blue,mark=none, + domain=-4:4,samples=20] + {x*x+x+104}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykeylist}{% + hide \x\ axis=\mchoice{true,false} (initially false), + hide axis=\mchoice{true,false} (initially false)} +Allows to hide either a selected axis or all of them. No outer rectangle, no tick marks and no labels will be drawn. Only titles and legends will be processed as usual. + +Axis scaling and clipping will be done as if you did not use |hide axis|. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + hide x axis, + hide y axis, + title={$x^2\cos(x)$}] + \addplot {cos(x)*x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + hide x axis, + axis y line=left, + title={$x^2\cos(x)$}] + \addplot {cos(x)*x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykeylist} + +\subsubsection{Color Bars} +\label{pgfplots:colorbar} +\PGFPlots\ supports mesh, surface and scatter plots which can use color maps. While color maps can be chosen as described in section~\ref{pgfplots:colormap}, they can be visualized using color bars. + +\begin{pgfplotskey}{colorbar=\mchoice{true,false} (initially false)} + Activates or deactivates color bars. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colorbar] + \addplot[mesh,ultra thick] {x}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colorbar,colormap/greenyellow] + \addplot[mesh,ultra thick] {x}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colorbar horizontal] + \addplot[mesh,ultra thick] {x}; + \end{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. + + 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 +\begin{codeexample}[code only] +\axis[every colorbar,colorbar shift,colorbar=false] + \addplot graphics {}; +\endaxis +\end{codeexample} + \noindent where the placement, alignment, appearance and other options are done by the two styles |every colorbar| and |colorbar shift|. These styles and the possible placement and alignment options are described below. + + \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 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} +\end{pgfplotskey} + +\begin{stylekey}{/pgfplots/colorbar right} + A style which re-defines |every colorbar| and |colorbar shift| such that color bars are placed right of their parent axis. + + This is the initial configuration. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colorbar right] + \addplot[mesh,thick,samples=150,domain=0.1:3] + {1/x}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The style |colorbar right| is defined to be +\begin{codeexample}[code only] +\pgfplotsset{ + colorbar right/.style={ + /pgfplots/colorbar=true, + /pgfplots/colorbar shift/.style={xshift=0.3cm}, + /pgfplots/every colorbar/.style={ + title=, + xlabel=, + ylabel=, + zlabel=, + legend entries=, + axis on top, + at={(parent axis.right of north east)}, + anchor=north west, + xmin=0, + xmax=1, + ymin=\pgfkeysvalueof{/pgfplots/point meta min}, + ymax=\pgfkeysvalueof{/pgfplots/point meta max}, + plot graphics/xmin=0, + plot graphics/xmax=1, + plot graphics/ymin=\pgfkeysvalueof{/pgfplots/point meta min}, + plot graphics/ymax=\pgfkeysvalueof{/pgfplots/point meta max}, + enlargelimits=false, + scale only axis, + height=\pgfkeysvalueof{/pgfplots/parent axis height}, + x=\pgfkeysvalueof{/pgfplots/colorbar/width}, + yticklabel pos=right, + xtick=\empty, + colorbar vertical/lowlevel, + } + }, + /pgfplots/colorbar vertical/lowlevel/.style={ + plot graphics/lowlevel draw/.code 2 args={% + \pgfuseshading{...} % some advanced basic level shading operations + } + }, +} +\end{codeexample} + \paragraph{Attention:} |colorbar right| \emph{re}-defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar right|: +\begin{codeexample}[code only] +% correct: +\begin{axis}[colorbar right, colorbar style={<some customization>}] +% wrong, colorbar right resets the customization: +\begin{axis}[colorbar style={<some customization>}, colorbar right] +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/pgfplots/colorbar left} + A style which re-defines |every colorbar| and |colorbar shift| such that color bars are placed left of their parent axis. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colorbar left] + \addplot[mesh,thick,samples=150] + {x*sin(deg(4*x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The style |colorbar left| is defined to be +\begin{codeexample}[code only] +\pgfplotsset{ + colorbar left/.style={ + /pgfplots/colorbar right, + /pgfplots/colorbar shift/.style={xshift=-0.3cm}, + /pgfplots/every colorbar/.append style={ + at={(parent axis.left of north west)}, + anchor=north east, + yticklabel pos=left, + } + } +} +\end{codeexample} + \paragraph{Attention:} |colorbar left| \emph{re}-defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar left| (see also the documentation for |colorbar right|). +\end{stylekey} + +\begin{stylekey}{/pgfplots/colorbar horizontal} + A style which re-defines |every colorbar| and |colorbar shift| such that color bars are placed below their parent axis, with a horizontal bar. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colorbar horizontal] + \addplot[only marks,scatter, + scatter src={mod(\coordindex,15)},samples=150] + {rand}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + This style is defined to be +\begin{codeexample}[code only] +\pgfplotsset{ + colorbar horizontal/.style={ + /pgfplots/colorbar=true, + /pgfplots/colorbar shift/.style={yshift=-0.3cm}, + /pgfplots/every colorbar/.style={ + title=, + xlabel=, + ylabel=, + zlabel=, + legend entries=, + axis on top, + at={(parent axis.below south west)}, + anchor=north west, + ymin=0, + ymax=1, + xmin=\pgfkeysvalueof{/pgfplots/point meta min}, + xmax=\pgfkeysvalueof{/pgfplots/point meta max}, + plot graphics/ymin=0, + plot graphics/ymax=1, + plot graphics/xmin=\pgfkeysvalueof{/pgfplots/point meta min}, + plot graphics/xmax=\pgfkeysvalueof{/pgfplots/point meta max}, + enlargelimits=false, + scale only axis, + width=\pgfkeysvalueof{/pgfplots/parent axis width}, + y=\pgfkeysvalueof{/pgfplots/colorbar/width}, + xticklabel pos=left, + ytick=\empty, + colorbar horizontal/lowlevel, + }% + },% + /pgfplots/colorbar horizontal/lowlevel/.style={% + plot graphics/lowlevel draw/.code 2 args={% + \pgfuseshading{...} % some advanced basic level shading operations + },% + },% +} +\end{codeexample} + \paragraph{Attention:} |colorbar horizontal| \emph{re}-defines |every colorbar|. That means any user customization must take place \emph{after} |colorbar horizontal|: +\begin{codeexample}[code only] +% correct: +\begin{axis}[colorbar horizontal, colorbar style={<some customization>}] +% wrong, colorbar horizontal resets the customization: +\begin{axis}[colorbar style={<some customization>}, colorbar horizontal] +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/pgfplots/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 intented 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. +\begin{predefinednode}{parent axis} + A node for the parent axis of a color bar. It is only valid for color bars. +\end{predefinednode} + + Thus, +\begin{codeexample}[code only] +\pgfplotsset{ + colorbar style={ + at={(parent axis.right of north east)}, + anchor=north west, + }, + colorbar shift/.style={xshift=0.3cm} +} +\end{codeexample} + \noindent places the colorbar in a way that its top-left (north west) corner is aligned right of the top right corner (|right of north east|) of its parent axis. Combining this with the |colorbar shift| is actually the same as the initial setting. + + Since color bars depend on some of its parent's properties, these properties are available as values of the following keys: +\begin{pgfplotskeylist}{point meta min,point meta max} + 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|. +\end{pgfplotskeylist} +\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}|. + + These values are only valid inside of color bars. +\end{pgfplotskeylist} + + Besides these values, each color bar inherits a list of styles of its parent axis, namely + + \begin{itemize} + \item |every tick|, + \item |every minor tick|, + \item |every major tick|, + \item |every axis grid|, + \item |every minor grid|, + \item |every major grid|, + \item |every tick label|. + \end{itemize} + This can be used to inherit line width and/or fonts. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + colorbar horizontal, + colorbar style={ + at={(0.5,1.03)},anchor=south, + xticklabel pos=upper + }, + title style={yshift=1cm}, + title=Customization: ``colorbar top''] + + \addplot[mesh,thick,samples=150,domain=0.1:3] + {x}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + colorbar horizontal, + colorbar style={ + at={(1,1.03)},anchor=south east, + width=0.5* + \pgfkeysvalueof{/pgfplots/parent axis width}, + xticklabel pos=upper, + }, + title style={yshift=1cm}, + title=More Customization: ``colorbar top''] + + \addplot[mesh,thick,samples=150,domain=0.1:3] + {x}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + Please take a look at the predefined styles |colorbar right|, |colorbar left| and |colorbar horizontal| for more details about configuration possibilities for |every colorbar|. + + \paragraph{Remark:} A color bar is just a normal axis. That means |every colorbar| can contain specifications where to place tick labels, extra ticks, scalings and most other features of a normal axis as well (except nested color bars). +\end{stylekey} + +\begin{pgfplotskey}{colorbar style=\marg{key-value list}} + A shortcut for |every colorbar/.append style=|\marg{key-value list}. It appends options to the colorbar style. +\end{pgfplotskey} + +\begin{pgfplotskey}{colorbar/width=\marg{dimension} (initially 0.5cm)} + Sets the width of a color bar. +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + view/az=45, + colorbar, + colorbar/width=2cm, + colormap/blackwhite] + + \addplot3[surf,domain=0:1,y domain=-3:3] {x*(1-x)*tanh(y)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + For vertical color bars, this sets the height. +\end{pgfplotskey} + + +\begin{stylekey}{/pgfplots/colorbar shift} + This style is installed after |every colorbar|. It is intented to contain only shift transformations like |xshift| and/or |yshift|. The reason to provide two separate styles is to allow easier deactivation of shift transformations. + +\begin{codeexample}[code only] +\pgfplotsset{ + colorbar shift/.style={xshift=1cm} +} +\end{codeexample} +\end{stylekey} + +\begin{predefinednode}{current colorbar axis} + A predefined node for the color bar of an axis. After |\end{axis}|, this node can be used to align further graphical elements at the color bar. Note that |current axis| refers to the axis as such while |current colorbar axis| refers to the color bar (which is an axis itsself). +\end{predefinednode} + +\begin{pgfplotscodekey}{colorbar/draw} + This code key belongs to the low level interface of colorbars. It is invoked whenever a color bar needs to be drawn. Usually, it won't be necessary to use or modify this key explicitly. + + In the context when this key is invoked, the styles inherited from the parent axis are already set and the required variables (see the documentation of |every colorbar|) are initialised. + + This code key can be replaced if one needs more than one color bar (or other wrinkles). + + The initial configuration is +\begin{codeexample}[code only] +\pgfplotsset{colorbar/draw/.code={% + \axis[every colorbar,colorbar shift,colorbar=false] + \addplot graphics {}; + \endaxis + } +} +\end{codeexample} + + 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} + +\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. + +\begin{keylist}{ + /tikz/font=\mchoice{\textbackslash normalfont,\textbackslash small,\textbackslash tiny,$\dotsc$}, + /pgfplots/max space between ticks=\marg{integer}, + /pgfplots/try min ticks=\marg{integer}, + /tikz/mark size=\marg{integer}} + These keys should be adjusted to the figure's dimensions. Use +\begin{codeexample}[code only] +\pgfplotsset{tick label style={font=\footnotesize}, + label style={font=\small}, + legend style={font=\small} +} +\end{codeexample} + to provide different fonts for different descriptions. + + The keys |max space between ticks| and |try min ticks| are described on page~\pageref{maxspacebetweenticks} and configure the approximate distance and number of successive tick labels (in |pt|). Please omit the |pt| suffix here. +\end{keylist} + +There are a couple of predefined scaling styles which set some of these options: + +\begin{stylekey}{/pgfplots/normalsize} + Re-initialises the standard scaling options of \PGFPlots. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[normalsize, + title=A ``normalsize'' figure, + xlabel=The $x$ axis, + ylabel=The $y$ axis, + minor tick num=1, + legend entries={Leg}] + \addplot {max(4*x,7*x)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The initial setting is +\begin{codeexample}[code only] +\pgfplotsset{ + normalsize/.style={ + /pgfplots/width=240pt, + /pgfplots/height=207pt, + /pgfplots/max space between ticks=35 + } +} +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/pgfplots/small} + Redefines several keys such that the axis is ``smaller''. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[small, + title=A ``small'' figure, + xlabel=The $x$ axis, + ylabel=The $y$ axis, + minor tick num=1, + legend entries={Leg}] + \addplot {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + The initial setting is +\begin{codeexample}[code only] +\pgfplotsset{ + small/.style={ + /pgfplots/width=6.5cm, + /pgfplots/height=, + /pgfplots/max space between ticks=25 + } +} +\end{codeexample} +Feel free to redefine the scaling -- the option may still be useful to get more ticks without typing too much. You could, for example, set |small,width=6cm|. +\end{stylekey} + +\begin{stylekey}{/pgfplots/footnotesize} + Redefines several keys such that the axis is even smaller. The tick labels will have |\footnotesize|. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[footnotesize, + title=A ``footnotesize'' figure, + xlabel=The $x$ axis, + ylabel=The $y$ axis, + minor tick num=1, + legend entries={Leg}] + \addplot+[const plot] + coordinates { + (0,0) (1,1) (3,3) (5,10) + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + The initial setting is +\begin{codeexample}[code only] +\pgfplotsset{ + footnotesize/.style={ + /pgfplots/width=5cm, + /pgfplots/height=, + legend style={font=\footnotesize}, + tick label style={font=\footnotesize}, + label style={font=\small}, + /pgfplots/max space between ticks=20, + every mark/.append style={mark size=8}, + major tick length=0.1cm, + minor tick length=0.066cm, + }, +} +\end{codeexample} +As for |small|, it can be convenient to set |footnotesize| and set |width| afterwards. + +See also the |compat=newest| method which causes the positions of |xlabel|, |ylabel| and |zlabel| to be right near the tick labels. +\end{stylekey} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.closingplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.closingplots.tex new file mode 100644 index 00000000000..d201284ac15 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.closingplots.tex @@ -0,0 +1,35 @@ + + +\subsection{Closing Plots (Filling the Area Under Plots)} +\begin{command}{\closedcycle} + Provide |\closedcycle| as \meta{trailing path commands} after |\addplot| to draw a closed line from the last plot coordinate to the first one. + + Use |\closedcycle| whenevery you intend to fill the area under a plot. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot {x^2+2} \closedcycle; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot+[fill] {x^2+2} \closedcycle; + \end{axis} +\end{tikzpicture} +\end{codeexample} + In case of stacked plots, |\closedcycle| connects the current plot with the previous plot instead of connecting with the $x$~axis\footnote{The implementation for stacked plots requires some additional logic to determine the filled area: \lstinline{\\closedcycle} will produce a \texttt{plot coordinates} command with \emph{reversed} coordinates of the previous plot. This is usually irrelevant for end users, but it assumes that the plot's type is symmetric. Since constant plots are inherently unsymmetric, \lstinline{\\closedcycle} will use \texttt{const plot mark right} as reversed sequence for \texttt{const plot mark left}.}. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[stack plots=y] + \addplot+[fill] coordinates + {(0,1) (1,1) (2,2) (3,2)} \closedcycle; + \addplot+[fill] coordinates + {(0,1) (1,1) (2,2) (3,2)} \closedcycle; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{command} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex new file mode 100644 index 00000000000..b0377e3e004 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex @@ -0,0 +1,116 @@ +\subsection{Skipping Or Changing Coordinates -- Filters} + +\begin{pgfplotsxycodekeylist}{\x\ filter,filter point} +The code keys |x filter| and |y filter| allow coordinate filtering which are based on a \emph{single} coordinate. A coordinate filter gets an input coordinate as |#1|, applies some operation and writes the result into the macro |\pgfmathresult|. If |\pgfmathresult| is empty afterwards, the coordinate is discarded. You can also set |\pgfmathresult| to |nan| or |inf| in which case the coordinate can be either discarded (if |unbounded coords=discard| is set) or the plot can be interrupted (the case |unbounded coords=jump|). + +The |filter point/.code| filter allows filtering dependent on all components forming a complete point ($x$, $y$ and $z$); it is described below. + +It is allowed if filters do not change |\pgfmathresult|. In this case, the unfiltered coordinate will be used. + +Coordinate filters are useful in automatic processing system, where \PGFPlots\ is used to display automatically generated plots. You may not want to filter your coordinates by hand, so these options provide a tool to do this automatically. + +The following filter adds $0.5$ to every $x$ coordinate. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[x filter/.code= + {\pgfmathadd{#1}{0.5}}] +\addplot coordinates { + (4,0) + (6,1) +}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +Please refer to~\cite[pgfmath manual]{tikz} for details about the math engine of \PGF. Please keep in mind that the math engine works with limited \TeX\ precision. + +During evaluation of the filter, the macro |\coordindex| contains the number of the current coordinate (starting with~$0$). Thus, the following filter discards all coordinates after the $5$th and before the $10$th. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + samples=20, + x filter/.code={ + \ifnum\coordindex>4 + \ifnum\coordindex<11 + \def\pgfmathresult{} + \fi + \fi + }] +\addplot {x^2}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +There is also a style key which simplifies selection by index, see below. + + \PGFPlots\ invokes the filter with argument |#1| set to the input coordinate. For $x$-filters, this is the $x$-coordinate as it is specified to |\addplot|, for $y$-filters it is the $y$-coordinate. + + If the corresponding axis is logarithmic, |#1| is the \emph{logarithm} (see |log basis x| and its variants) of the coordinate as a real number, for example |#1=4.2341|. In case the logarithm was undefined, the argument will be empty. + + The arguments to coordinate filters are minimally preprocessed: first, for logarithmic axes, the \emph{log} of the argument is supplied. Second, any high level coordinate maps like |x coord trafo| (which may be used to map dates to numbers or string to numbers or so) are applied. In consequence, the |#1| argument is supposed to be a number. No further transformation has been applied. + + Occasionally, it might be handy to get the ``raw'', completely unprocessed input coordinate as it has been reported by the coordinate input routine. This unprocessed data is available in the three math parser constants \declareandlabel{rawx}, \declareandlabel{rawy} and \declareandlabel{rawz} (use \declareandlabel{\pgfmathrawx}, \declareandlabel{\pgfmathrawy} and \declareandlabel{\pgfmathrawz} as a way to assign the value of interest to |\pgfmathresult|). All these values are ready for use in filters (and some other methods influence plots as well). + + If key filters are invoked for |plot table|, access to the current row's data can be achieved using |\thisrow|\marg{column name} (and its variants). This includes all columns of the table. + + The |filter point| key is more technical. It doesn't take an argument: its arguments are given in terms of the |pgfkeys| variables |/data point x|, |/data point y| and |/data point z|. It may change its coordinates using |\pgfkeyssetvalue{/data point x}|\marg{the new value}; access to variables can be get with |\pgfkeysvalueof{/data point/x}| or, if the argument shall be written into a macro, with |\pgfkeysgetvalue|. This filter is evaluated after the other ones. + +\end{pgfplotsxycodekeylist} + +\begin{stylekey}{/pgfplots/skip coords between index=\marg{begin}\marg{end}} + A style which appends an |x filter| which discards selected coordinates. The selection is done by index where indexing starts with~$0$, see |\coordindex|. Every coordinate with index $\meta{begin} \le i < \meta{end}$ will be skipped. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + samples=20, + skip coords between index={5}{11}, + skip coords between index={15}{18}] + +\addplot {x^2}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{stylekey} + +\begin{pgfplotskey}{each nth point=\marg{integer}} + A style which appends an |x filter| which discards all but each $n$th input coordinate. +\index{Downsampling} +\end{pgfplotskey} + +\begin{pgfplotsxykey}{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}. + + 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. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + restrict y to domain=-10:10, + samples=1000, + % some fine tuning for the display: + width=10cm, height=210pt, + xmin=-4.7124, xmax=4.7124, + xtick={-4.7124,-1.5708,...,10}, + xticklabels={$-\frac32 \pi$,$-\pi/2$,$\pi/2$,$\frac32 \pi$}, + axis x line=center, + axis y line=center] + +\addplot[blue] gnuplot[id=tangens,domain=-1.5*pi:1.5*pi] {tan(x)}; +\legend{$\tan(x)$} +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykey} + +\begin{pgfplotskey}{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. + + 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} + +\begin{pgfplotskey}{filter discard warning=\mchoice{true,false} (initially true)} + Issues a notification in your logfile whenever coordinate filters discard coordinates. +\end{pgfplotskey} + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.errorbars.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.errorbars.tex new file mode 100644 index 00000000000..84166213573 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.errorbars.tex @@ -0,0 +1,184 @@ + +\subsection{Error Bars} +\label{sec:errorbars} +{% +\def\pgfplotserror#1{\ensuremath{\epsilon_{#1}}}% +\PGFPlots\ supports error bars for normal and logarithmic plots. + +Error bars are enabled for each plot separately, using \meta{options} after |\addplot|: +\pgfmanualpdflabel{/pgfplots/error bars}{}% +\begin{codeexample}[code only] +\addplot+[error bars/.cd,x dir=both,y dir=both] ... +\end{codeexample} +Error bars inherit all drawing options of the associated plot, but they use their own marker and style arguments additionally. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[error bars/.cd, + y dir=plus,y explicit] +coordinates { + (0,0) +- (0.5,0.1) + (0.1,0.1) +- (0.05,0.2) + (0.2,0.2) +- (0,0.05) + (0.5,0.5) +- (0.1,0.2) + (1,1) +- (0.3,0.1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} +\addplot+[error bars/.cd, + y dir=both,y explicit, + x dir=both,x fixed=0.05, + error mark=diamond*] +coordinates { + (0,0) +- (0.5,0.1) + (0.1,0.1) +- (0.05,0.2) + (0.2,0.2) +- (0,0.05) + (0.5,0.5) +- (0.1,0.2) + (1,1) +- (0.3,0.1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}} +\begin{codeexample}[] +\pgfplotstabletypeset{pgfplots.testtable2.dat} + +\begin{tikzpicture} +\begin{loglogaxis} +\addplot+[error bars/.cd, + x dir=both,x fixed relative=0.5, + y dir=both,y explicit relative, + error mark=triangle*] + table[x=x,y=y,y error=errory] + {pgfplots.testtable2.dat}; +\end{loglogaxis} +\end{tikzpicture} +\end{codeexample} +%-------------------------------------------------- +% coordinates { +% (32,32) +% (64,64) +% (128,128) +- (0,0.3) +% (1024,1024) +- (0,0.2) +% (32068,32068) +- (0,0.6) +% (64000,64000) +- (0,0.6) +% (128000,128000) +- (0,0.6) +% }; +%-------------------------------------------------- + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[enlargelimits=false] +\addplot[red,mark=*] + plot[error bars/.cd, + y dir=minus,y fixed relative=1, + x dir=minus,x fixed relative=1, + error mark=none, + error bar style={dotted}] +coordinates + {(0,0) (0.1,0.1) (0.2,0.2) + (0.5,0.5) (1,1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{pgfplotsxykey}{error bars/\x\ dir=\mchoice{none,plus,minus,both} (initially none)} +Draws either no error bars at all, only marks at $x+\pgfplotserror x$, only marks at $x-\pgfplotserror x$ or marks at both, $x+\pgfplotserror x$ and $x-\pgfplotserror x$. The $x$-error $\pgfplotserror x$ is acquired using one of the following options. + +The same holds for the |y dir| option. +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{error bars/\x\ fixed=\marg{value} (initially 0)} +Provides a common, absolute error $\pgfplotserror x=\text{\meta{value}}$ for all input coordinates. + +For linear $x$~axes, the error mark is drawn at $x \pm \pgfplotserror x$ while for logarithmic $x$~axes, it is drawn at $\log( x \pm \pgfplotserror x)$. Computations are performed in \PGF's floating point arithmetics. +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{error bars/\x\ fixed relative=\marg{percent} (initially 0)} +Provides a common, relative error $\pgfplotserror x = \text{\meta{percent}} \cdot x$ for all input coordinates. The argument \meta{percent} is thus given relatively to input $x$ coordinates such that $\text{\meta{percent}} = 1$ means $100\%$. + +Error marks are thus placed at $x \cdot (1 \pm \pgfplotserror x)$ for linear axes and at $\log(x \cdot (1 \pm \pgfplotserror x))$ for logarithmic axes. Computations are performed in floating point for linear axis and using the identity $\log(x \cdot (1 \pm \pgfplotserror x)) = \log(x) + \log( 1 \pm \pgfplotserror x)$ for logarithmic scales. +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{error bars/\x\ explicit} +Configures the error bar algorithm to draw $x$-error bars at any input coordinate for which user-specified errors are available. + Each error is interpreted as absolute error, see |x fixed| for details. + +The different input formats of errors are described in section~\ref{sec:errorbar:input}. +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{error bars/\x\ explicit relative} +Configures the error bar algorithm to draw $x$-error bars at any input coordinate for which user-specified errors are available. + Each error is interpreted as relative error, that means error marks are placed at $x (1 \pm \text{\meta{value}}(x))$ (works as for |error bars/x fixed relative|). +\end{pgfplotsxykey} + + +\begin{pgfplotskey}{error bars/error mark=\meta{marker}} +Sets an error marker for any error bar. \marg{marker} is expected to be a valid plot mark, see section~\ref{sec:markers}. +\end{pgfplotskey} + +\begin{pgfplotskey}{error bars/error mark options=\marg{key-value-list}} +Sets a key-value list of options for any error mark. This option works similary to the \Tikz\ `|mark options|' key. +\end{pgfplotskey} + +\begin{pgfplotskey}{error bars/error bar style=\marg{key-value-list}} +Appends the argument to `|/pgfplots/every error bar|' which is installed at the beginning of every error bar. +\end{pgfplotskey} + +\begin{pgfplotscodetwokey}{error bars/draw error bar} +Allows to change the default drawing commands for error bars. The two arguments are +\begin{itemize} +\item the source point, $(x,y)$ and +\item the target point, $(\tilde x,\tilde y)$. +\end{itemize} +Both are determined by \PGFPlots\ according to the options described above. The default code is +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/error bars/draw error bar/.code 2 args={% + \pgfkeysgetvalue{/pgfplots/error bars/error mark}% + {\pgfplotserrorbarsmark}% + \pgfkeysgetvalue{/pgfplots/error bars/error mark options}% + {\pgfplotserrorbarsmarkopts}% + \draw #1 -- #2 node[pos=1,sloped,allow upside down] {% + \expandafter\tikz\expandafter[\pgfplotserrorbarsmarkopts]{% + \expandafter\pgfuseplotmark\expandafter{\pgfplotserrorbarsmark}% + \pgfusepath{stroke}}% + }; + } +} +\end{codeexample} +\end{pgfplotscodetwokey} + +\subsubsection{Input Formats of Error Coordinates} +\label{sec:errorbar:input}% +Error bars with explicit error estimations for single data points require some sort of input format. This applies to `|error bars/|\meta{[xy]}| explicit|' and `|error bars/|\meta{[xy]}| explicit relative|'. + +Error bar coordinates can be read from `|plot coordinates|' or from `|plot table|'. The inline plot coordinates format is +\begin{codeexample}[code only] +\addplot coordinates { + (1,2) +- (0.4,0.2) + (2,4) +- (1,0) + (3,5) + (4,6) +- (0.3,0.001) +} +\end{codeexample} +where $(1,2) \pm (0.4,0.2)$ is the first coordinate, $(2,4) \pm (1,0)$ the second and so forth. The point $(3,5)$ has no error coordinate. + +The `|plot table|' format is +\begin{codeexample}[code only] +\addplot table[x error=COLNAME,y error=COLNAME] +\end{codeexample} +or +\begin{codeexample}[code only] +\addplot table[x error index=COLINDEX,y error index=COLINDEX] +\end{codeexample} +These options are used as the `|x|' and `|x index|' options. + +You can supply error coordinates even if they are not used at all; they will be ignored silently in this case. + +}% diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.gridoptions-axiscoordinates.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.gridoptions-axiscoordinates.tex new file mode 100644 index 00000000000..aa924828fa8 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.gridoptions-axiscoordinates.tex @@ -0,0 +1,178 @@ + + + +\subsection{Grid Options} + +\begin{pgfplotsxykeylist}{\x minorgrids=\mchoice{true,false} (initially false),\x majorgrids=\mchoice{true,false} (initially false),grid=\mchoice{minor,major,both,none} (initially false)} +Enables/disables different grid lines. Major grid lines are placed at the normal tick positions (see |xmajorticks|) while minor grid lines are placed at minor ticks (see |xminorticks|). + +This example employs the coordinates defined on page~\pageref{page:plotcoords:src}. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{loglogaxis}[ + xlabel={\textsc{Dof}}, + ylabel={$L_2$ Error}, + grid=major +] +% see above for this macro: +\plotcoords +\end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{loglogaxis}[ + grid=both, + tick align=outside, + tickpos=left] +\addplot coordinates + {(100,1e-4) (500,1e-5) (1000,3e-6)}; +\addplot coordinates + {(100,1e-5) (500,4e-6) (1000,2e-6)}; +\end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + +Grid lines will be drawn before tick lines are processed, so ticks will be drawn on top of grid lines. You can configure the appearance of grid lines with the styles +\begin{codeexample}[code only] +\pgfplotsset{grid style={help lines}} % modifies the style `every axis grid' +\pgfplotsset{minor grid style={color=blue}} % modifies the style `every minor grid' +\pgfplotsset{major grid style={thick}} %modifies the style `every major grid' +\end{codeexample} +\end{pgfplotsxykeylist} + + +\subsection{Accessing Axis Coordinates for Annotations} +\label{sec:axis:coords}% +\begin{coordinatesystem}{axis cs} +\PGFPlots\ provides a new coordinate system for use inside of an axis, the ``axis coordinate system'', |axis cs|. + +It can be used to draw any \Tikz-graphics at axis coordinates. It is used like +\begin{codeexample}[code only] +\draw + (axis cs:18943,2.873391e-05) +|- (axis cs:47103,8.437499e-06); +\end{codeexample} +\begin{codeexample}[] +\tikzstyle{every pin}=[fill=white, + draw=black, + font=\footnotesize] +\begin{tikzpicture} + \begin{loglogaxis}[ + xlabel={\textsc{Dof}}, + ylabel={$L_2$ Error}] + + \addplot coordinates { + (11, 6.887e-02) + (71, 3.177e-02) + (351, 1.341e-02) + (1471, 5.334e-03) + (5503, 2.027e-03) + (18943, 7.415e-04) + (61183, 2.628e-04) + (187903, 9.063e-05) + (553983, 3.053e-05) + }; + + \node[coordinate,pin=above:{Bad!}] + at (axis cs:5503,2.027e-03) {}; + \node[coordinate,pin=left:{Good!}] + at (axis cs:187903,9.063e-05) {}; + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{loglogaxis}[ + xlabel=\textsc{Dof}, + ylabel=$L_2$ Error +] +\draw + (axis cs:1793,4.442e-05) + |- (axis cs:4097,1.207e-05) + node[near start,left] + {$\frac{dy}{dx} = -1.58$}; + +\addplot coordinates { + (5, 8.312e-02) + (17, 2.547e-02) + (49, 7.407e-03) + (129, 2.102e-03) + (321, 5.874e-04) + (769, 1.623e-04) + (1793, 4.442e-05) + (4097, 1.207e-05) + (9217, 3.261e-06) +}; +\end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + +\paragraph{Attention:} Whenever you draw additional graphics, consider using |axis cs|! It applies any logarithms, data scaling transformations or whatever \PGFPlots\ usually does! + +There is also a low--level interface to access the transformations and coordinates, see section~\ref{sec:pgfplots:lowlevel} on page~\pageref{sec:pgfplots:lowlevel}. +\end{coordinatesystem} + +\begin{coordinatesystem}{rel axis cs} +The ``relative axis coordinate system'', |rel axis cs|, uses the complete axis vectors as units. That means `$x=0$' denotes the point on the lower $x$ axis range and `$x=1$' the point on the upper $x$ axis range (see the remark below for |x dir=reverse|). + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + + \addplot3[surf] {x^2 - y^2}; + \draw (rel axis cs:0,0,1) + -- (rel axis cs:1,1,1); +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xlabel=$x$, + ylabel=$y$, + zlabel=$z$, + every axis x label/.style={ + at={(rel axis cs:0.5,-0.15,-0.15)}}, + every axis y label/.style={ + at={(rel axis cs:1.15,0.5,-0.15)}}, + every axis z label/.style={ + at={(rel axis cs:-0.15,-0.15,0.5)}}, +] + + \addplot3[surf] {x*(1-x)*y}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + Points identified by |rel axis cs| use the syntax + + |(rel axis cs:|\meta{x}|,|\meta{y}|)| or + + |(rel axis cs:|\meta{x}|,|\meta{y}|,|\meta{z}|)| + + \noindent where \meta{x}, \meta{y} and \meta{z} are coordinates or constant mathematical expressions. The second syntax is only available in three dimensional axes. + + There is one speciality: if you reverse an axis (with |x dir=reverse|), points provided by |rel axis cs| will be \emph{unaffected} by the axis reversal. This is intented to provide consistent placement even for reversed axes. Use |allow reversal of rel axis cs=false| to disable this feature. + +There is also a low--level interface to access the transformations and coordinates, see section~\ref{sec:pgfplots:lowlevel} on page~\pageref{sec:pgfplots:lowlevel}. +\end{coordinatesystem} + +\begin{predefinednode}{current plot begin} + This coordinate will be defined for every plot and can be used is \meta{trailing path commands} or after a plot. It is the first coordinate of the current plot. +\end{predefinednode} + +\begin{predefinednode}{current plot end} + This coordinate will be defined for every plot. It is the last coordinate of the current plot. +\end{predefinednode} + +\begin{pgfplotskey}{allow reversal of rel axis cs=\mchoice{true,false} (initially true)} + A fine tuning key which specifies how to deal with |x dir=reverse| and |rel axis cs| and |ticklabel cs|. + + The initial configuration |true| means that points placed with |rel axis cs| and/or |ticklabel cs| will be at the same position inside of the axes even if its ordering has been reversed. The choice |false| will disable the special treatment of |x dir=reverse|. +\end{pgfplotskey} 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 new file mode 100644 index 00000000000..56114469f88 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex @@ -0,0 +1,1176 @@ + +\subsection{Markers, Linestyles, (Background-) Colors and Colormaps} +\label{sec:markers}% +The following options of \Tikz\ are available to plots. + +\subsubsection{Markers} +This list is copied from~\cite[section~29]{tikz}: +\pgfmanualpdflabel{/tikz/mark}{}% +\begingroup +\newenvironment{longdescription}[0]{% + \begin{list}{}{% + \leftmargin=4.3cm + \setlength{\labelwidth}{4.3cm}% + \renewcommand{\makelabel}[1]{\hfill\textbf{\texttt{##1}}}% + }% +}{% + \end{list}% +}% +\def\showit#1{% + \tikz\draw[% + gray, + thin, + mark options={fill=yellow!80!black,draw=black,scale=2}, + x=0.8cm,y=0.3cm, + #1] + plot coordinates {(0,0) (1,1) (2,0) (3,1)};% +}% +\def\showitpgfplots#1{% +\begin{tikzpicture}[baseline] + \begin{axis}[anchor=north,xticklabels=,yticklabels=,zticklabels=,width=5cm] + \addplot3[gray, thin, mark options={scale=2,fill=yellow!80!black,draw=black},#1] + plot coordinates {(0,0,0) (0.3,0.6,0.3) (2,0,0.1) (2.3,1,0.2)}; + \end{axis} +\end{tikzpicture}% +}% +\begin{longdescription} + \item[mark=*] \showit{mark=*} + \item[mark=x] \showit{mark=x} + \item[mark=+] \showit{mark=+} +% \item[mark=ball] \showit{mark=ball} +\end{longdescription} +And with |\usetikzlibrary{plotmarks}|: +\begin{longdescription} + \item[mark=$-$] \showit{mark=-} + \item[mark=$\vert$] \showit{mark=|} + \item[mark=o] \showit{mark=o} + \item[mark=asterisk] \showit{mark=asterisk} + \item[mark=star] \showit{mark=star} + \item[mark=oplus] \showit{mark=oplus} + \item[mark=oplus*] \showit{mark=oplus*} + \item[mark=otimes] \showit{mark=otimes} + \item[mark=otimes*] \showit{mark=otimes*} + \item[mark=square] \showit{mark=square} + \item[mark=square*] \showit{mark=square*} + \item[mark=triangle] \showit{mark=triangle} + \item[mark=triangle*] \showit{mark=triangle*} + \item[mark=diamond] \showit{mark=diamond} + \item[mark=diamond*] \showit{mark=diamond*} + \item[mark=pentagon] \showit{mark=pentagon} + \item[mark=pentagon*] \showit{mark=pentagon*} + \item[mark=text] \showit{mark=text,every mark/.append style={scale=0.5}} + + This marker is special as it can be configured freely. The character (or even text) used is configured by a set of variables, see below. + \item[mark=cube] \showitpgfplots{mark=cube} + + This marker is only available inside of a \PGFPlots\ axis, it draws a cube with axis parallel faces. Its sizes can be configured separately, see below. + \item[mark=cube*] \showitpgfplots{mark=cube*} + + \item[User defined] It is possible to define new markers with |\pgfdeclareplotmark|, see below. +\end{longdescription} +All these options have been drawn with the additional options +\begin{codeexample}[code only] +\draw[ + gray, + thin, + mark options={% + scale=2,fill=yellow!80!black,draw=black + } +] +\end{codeexample} +Please see section~\ref{sec:colors} for how to change draw- and fill colors. + +\begin{key}{/tikz/mark size=\marg{dimension}} + This \Tikz\ option allows to set marker sizes to \marg{dimension}. For circular markers, \marg{dimension} is the radius, for other plot marks it is about half the width and height. +\end{key} + +\begin{pgfplotsxykey}{cube/size \x=\marg{dimension} (initially |\textbackslash pgfplotmarksize|)} + Sets the size for |mark=cube| separately for every axis. +\end{pgfplotsxykey} +\begin{key}{/tikz/every mark} + This \Tikz\ style can be reconfigured to set marker appearance options like colors or transformations like scaling or rotation. \PGFPlots\ appends its |cycle list| options to this style. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[y=2cm] + \addplot coordinates + {(-2,0) (-1,1) (0,0) (1,1) (2,0)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\tikzset{every mark/.append style={scale=2}} +\begin{tikzpicture} +\begin{axis}[y=2cm] + \addplot coordinates + {(-2,0) (-1,1) (0,0) (1,1) (2,0)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{key} + +\begin{stylekey}{/pgfplots/no markers} + Disables plot marks. + + If this style is provided as argument to a complete axis, it is appended to |every axis plot post| such that it disables markers even for |cycle list|s which contain markers. +\end{stylekey} + +\begin{key}{/tikz/mark options=\marg{options}} + Resets |every mark| to \marg{options}. +\end{key} + + +\begin{key}{/pgf/text mark=\marg{text} (initially p)} + Changes the text shown by |mark=text|. + + With |/pgf/text mark=m|: \pgfkeys{/pgf/text mark=m}\showit{mark=text,every mark/.append style={scale=0.5}} + + With |/pgf/text mark=A|: \pgfkeys{/pgf/text mark=A}\showit{mark=text,every mark/.append style={scale=0.5}} + + There is no limitation about the number of characters or whatever. In fact, any \TeX\ material can be inserted as \marg{text}, including images. +\end{key} +\begin{key}{/pgf/text mark style=\marg{options for \texttt{mark=text}}} + Defines a set of options which control the appearance of |mark=text|. + + If |/pgf/text mark as node=false| (the default), \marg{options} is provided as argument to |\pgftext| -- which provides only some basic keys like |left|, |right|, |top|, |bottom|, |base| and |rotate|. + + If |/pgf/text mark as node=true|, \marg{options} is provided as argument to |\node|. This means you can provide a very powerful set of options including |anchor|, |scale|, |fill|, |draw|, |rounded corners| etc. +\end{key} +\begin{key}{/pgf/text mark as node=\mchoice{true,false} (initially false)} + Configures how |mark=text| will be drawn: either as |\node| or as |\pgftext|. + + The first choice is highly flexible and possibly slow, the second is very fast and usually enough. +\end{key} + +\begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}} + Defines a new marker named \marg{plot mark name}. Whenever it is used, \marg{code} will be invoked. It is suppose to contain (preferrable \PGF\ basic level) drawing commands. During \marg{code}, the coordinate system's origin denotes the coordinate where the marker shall be placed. + + Please refer to~\cite{tikz} section ``Mark Plot Handler'' for more detailed information. +\end{command} + + + +\begin{stylekey}{/pgfplots/every axis plot post (initially {})} +The |every axis plot post| style can be used to overwrite parts (or all) of the drawing styles which are assigned for plots. +\begin{codeexample}[] +% Overwrite any cycle list: +\pgfplotsset{ + every axis plot post/.append style={ + mark=triangle, + every mark/.append style={rotate=90}}} +\begin{tikzpicture} +\begin{axis}[y=2cm] + \addplot coordinates + {(-2,0) (-1,1) (0,0) (1,1) (2,0)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{stylekey} + +Markers paths are not subjected to clipping as other parts of the figure. Markers are either drawn completely or not at all. + +\Tikz\ offers more options for marker fine tuning, please refer to~\cite{tikz} for details. + +\subsubsection{Line Styles} +\def\showit#1{% + \tikz\draw[% + black, + x=0.8cm,y=0.3cm, + #1] + plot coordinates {(0,0) (1,1) (2,0) (3,1)};% +}% +The following line styles are predefined in \Tikz. +\begin{stylekey}{/tikz/solid} + \showit{style=solid} +\end{stylekey} + +\begin{stylekey}{/tikz/dotted} + \showit{style=dotted} +\end{stylekey} + +\begin{stylekey}{/tikz/densely dotted} + \showit{style=densely dotted} +\end{stylekey} + +\begin{stylekey}{/tikz/loosely dotted} + \showit{style=loosely dotted} +\end{stylekey} + +\begin{stylekey}{/tikz/dashed} + \showit{style=dashed} +\end{stylekey} + +\begin{stylekey}{/tikz/densely dashed} + \showit{style=densely dashed} +\end{stylekey} + +\begin{stylekey}{/tikz/loosely dashed} + \showit{style=loosely dashed} +\end{stylekey} +\noindent since these styles apply to markers as well, you may want to consider using +\begin{codeexample}[code only] +\pgfplotsset{ + every mark/.append style={solid} +} +\end{codeexample} +\noindent in marker styles. + +Besides linestyles, \PGF\ also offers (a lot of) arrow heads. Please refer to~\cite{tikz} for details. +\endgroup + + +\subsubsection{Font Size and Line Width} +Often, one wants to change line width and font sizes for plots. This can be done using the following options of \Tikz. + +\begin{key}{/tikz/font=\marg{font name} (initially \textbackslash normalfont)} + Sets the font which is to be used for text in nodes (like tick labels, legends or descriptions). + + A font can be any \LaTeX\ argument like |\footnotesize| or |\small\bfseries|\footnote{Con\TeX t and plain \TeX\ users need to provide other statements, of course.}. + + It may be useful to change fonts only for specific axis descriptions, for example using +\begin{codeexample}[code only] +\pgfplotsset{ + tick label style={font=\small}, + label style={font=\small}, + legend style={font=\footnotesize} +} +\end{codeexample} + + See also the predefined styles |normalsize|, |small| and |footnotesize| in section~\ref{sec:scaling:styles}. +\end{key} + +\begin{key}{/tikz/line width=\marg{dimension} (initially 0.4pt)} + Sets the line width. Please note that line widths for tick lines and grid lines are predefined, so it may be necessary to override the styles |every tick| and |every axis grid|. + + The |line width| key is changed quite often in \Tikz. You should use +\begin{codeexample}[code only] +\pgfplotsset{every axis/.append style={line width=1pt}} +\end{codeexample} + or +\begin{codeexample}[code only] +\pgfplotsset{every axis/.append style={thick}} +\end{codeexample} + to change the overall line width. To also adjust ticks and grid lines, one can use +\begin{codeexample}[code only] +\pgfplotsset{every axis/.append style={ + line width=1pt, + tick style={line width=0.6pt}}} +\end{codeexample} + or styles like +\begin{codeexample}[code only] +\pgfplotsset{every axis/.append style={ + thick, + tick style={semithick}}} +\end{codeexample} + The `|every axis plot|' style can be used to change line widths for plots only. +\end{key} + +\begin{keylist}[/tikz]{thin,ultra thin,very thin,semithick,thick,very thick,ultra thick} + These \Tikz\ styles provide different predefined line widths. +\end{keylist} + +This example shows the same plots as on page~\pageref{page:plotcoords:src} (using |\plotcoords| as place holder for the commands on page~\pageref{page:plotcoords:src}), with different line width and font size. +\begin{codeexample}[] +\pgfplotsset{every axis/.append style={ + font=\large, + line width=1pt, + tick style={line width=0.8pt}}} +\begin{tikzpicture} + \begin{loglogaxis}[ + legend style={at={(0.03,0.03)}, + anchor=south west}, + xlabel=\textsc{Dof}, + ylabel=$L_2$ Error + ] + % see above for this macro: + \plotcoords + \legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\pgfplotsset{every axis/.append style={ + font=\footnotesize, + thin, + tick style={ultra thin}}} +\begin{tikzpicture} + \begin{loglogaxis}[ + xlabel=\textsc{Dof}, + ylabel=$L_2$ Error + ] + % see above for this macro: + \plotcoords + \legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + + +\subsubsection{Colors} +\label{sec:colors} +{% +\def\showcolorandname#1{% + \showcolor{#1}~\texttt{\pgfmanualpdflabel{#1}{#1}}% +}% +\def\showcolor#1{% + \tikz \draw[black,fill={#1}] (0,0) rectangle (1em,0.6em);% +}% +\PGF\ uses the color support of |xcolor|. Therefore, the main reference for how to specify colors is the |xcolor| manual~\cite{xcolor}. The \PGF\ manual~\cite{tikz} is the reference for how to select colors for specific purposes like drawing, filling, shading, patterns etc.\ This section contains a short overview over the specification of colors in~\cite{xcolor} (which is not limited to \PGFPlots). + +The package |xcolor| defines a set of predefined colors, namely +\showcolorandname{red}, +\showcolorandname{green}, +\showcolorandname{blue}, +\showcolorandname{cyan}, +\showcolorandname{magenta}, +\showcolorandname{yellow}, +\showcolorandname{black}, +\showcolorandname{gray}, +\showcolorandname{white}, +\showcolorandname{darkgray}, +\showcolorandname{lightgray}, +\showcolorandname{brown}, +\showcolorandname{lime}, +\showcolorandname{olive}, +\showcolorandname{orange}, +\showcolorandname{pink}, +\showcolorandname{purple}, +\showcolorandname{teal}, +\showcolorandname{violet}. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[enlarge x limits=false] + \addplot[red,samples=500] {sin(deg(x))}; + + \addplot[orange,samples=7] {sin(deg(x))}; + + \addplot[teal,const plot, + samples=14] {sin(deg(x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +Besides predefined colors, it is possible to \emph{mix} two (or more) colors. For example, \showcolorandname{red!30!white} contains $30\%$ of \showcolorandname{red} and $70\%$ of \showcolorandname{white}. Consequently, one can build \showcolorandname{red!70!white} to get $70\%$ red and $30\%$ white or \showcolorandname{red!10!white} for $10\%$ red and $90\%$ white. This mixing can be done with any color, for example \showcolorandname{red!50!green}, \showcolorandname{blue!50!yellow} or \showcolorandname{green!60!black}. + +A different type of color mixing is supported, which allows to take $100\%$ of \emph{each} component. For example, \showcolorandname{rgb,2:red,1;green,1} will add $1/2$ part \showcolorandname{red} and $1/2$ part \showcolorandname{green} and we reproduced the example from above. Using the denominator~$1$ instead of~$2$ leads to \showcolorandname{rgb,1:red,1;green,1} which uses $1$ part \showcolorandname{red} and $1$ part \showcolorandname{green}. Many programs allow to select pieces between $0,\dotsc,255$, so a denominator of $255$ is useful. Consequently, \showcolorandname{rgb,255:red,231;green,84;blue,121} uses $231/255$ red, $84/255$ green and $121/255$. This corresponds to the standard RGB color $(231,84,121)$. Other examples are \showcolorandname{rgb,255:red,32;green,127;blue,43}, \showcolorandname{rgb,255:red,178;green,127;blue,43}, \showcolorandname{rgb,255:red,169;green,178;blue,43}. + +It is also possible to use RGB values, the HSV color model or the HTML color syntax directly. However, this requires some more programming. I suppose this is the fastest (and probably the most uncomfortable) method to use colors. For example, +\begin{codeexample}[] +\definecolor{color1}{rgb}{1,1,0} +\tikz \fill[color1] + (0,0) rectangle (1em,0.6em); +\end{codeexample} +\noindent creates the color with $100\%$ red, $100\%$ green and $0\%$ blue; + +\begin{codeexample}[] +\definecolor{color1}{HTML}{D0B22B} +\tikz \fill[color1] + (0,0) rectangle (1em,0.6em); +\end{codeexample} +\noindent creates the color with $208/255$ pieces red, $178/255$ pieces green and $43$ pieces blue, specified in standard HTML notation. Please refer to the |xcolor| manual~\cite{xcolor} for more details and color models. + +The |xcolor| package provides even more methods to combine colors, among them the prefix `|-|' (minus) which changes the color into its complementary color (\showcolorandname{-black}, \showcolorandname{-white}, \showcolorandname{-red}) or color wheel calculations. Please refer to the |xcolor| manual~\cite{xcolor}. +}% + +\begin{keylist}{ + /tikz/color=\marg{a color}, + /tikz/draw=\marg{stroke color}, + /tikz/fill=\marg{fill color}} + These keys are (generally) used to set colors. Use |color| to set the color for both, drawing and filling. Instead of |color=|\marg{color name} you can simply write \marg{color name}. The |draw| and |fill| keys only set colors for stroking and filling, respectively. + + Use |draw=none| to disable drawing and |fill=none| to disable filling\footnote{Up to now, plot marks always have a stroke color (some also have a fill color). This restriction may be lifted in upcoming versions.}.% This does also work for markers. +%-------------------------------------------------- +% \ begin{codeexample}[] +% \begin{tikzpicture} +% \begin{axis} +% \addplot+[only marks,mark=square*, +% mark options={fill=red!50!white,draw=none}] +% {4*x^2 - 2*x +4 }; +% \end{axis} +% \end{tikzpicture} +% \end{codeexample} +%-------------------------------------------------- + + Since these keys belong to \Tikz, the complete documentation can be found in the \Tikz\ manual~\cite[Section ``Specifying a Color'']{tikz}. +\end{keylist} + +\subsubsection{Color Maps} +\label{pgfplots:colormap} +\begin{pgfplotskey}{colormap name=\marg{color map name} (initially hot)} + Changes the current color map to the already defined map named \marg{color map name}. The predefined color map is + + \begin{tabular}{>{\ttfamily}ll} + hot & \pgfplotsshowcolormap{hot}\\ + \end{tabular} + + Further color maps are described below. + + Colormaps can be used, for example, in scatter plots (see section~\ref{pgfplots:scatter}). + + You can use |colormap| to create new color maps (see below). +\end{pgfplotskey} + +\begin{pgfplotskey}{colormap=\marg{name}\marg{color specification}} + Defines a new colormap named \marg{name} according to \marg{color specification} and activates it using |colormap name=|\marg{name}. + + The \marg{color specification} is a sequence of positions and associated colors where linear interpolation is applied inbetween. The syntax is very similar as the one used for \PGF\ shadings described in~\cite[VIII -- Shadings]{tikz}: it is a semicolon--separated series of + + \meta{color type}|(|\meta{offset}|)=(|\meta{color value}|); |: + +\begin{codeexample}[code only] +% possibility 1: like PGF shadings: +rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb255(2cm)=(0,0,255); gray(3cm)=(0.3); color(4cm)=(green) +\end{codeexample} +\pgfplotsshowcolormapexample{rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb255(2cm)=(0,0,255); gray(3cm)=(0.3); color(4cm)=(green)} + + If the distance between successive colors is the same anyway, one can skip the \meta{offset}. The `|;|' separators are not necessary as well: + +\begin{codeexample}[code only] +% (simplified) possibility 2: skip `;' and length arguments: +rgb=(1,0,0) rgb=(0,1,0) rgb255=(0,0,255) gray=(0.3) color=(green) +\end{codeexample} +\pgfplotsshowcolormapexample{rgb=(1,0,0) rgb=(0,1,0) rgb255=(0,0,255) gray=(0.3) color=(green)} + + It is also possible to provide non-uniform distances between the different colors -- if all single positions can be projected onto a uniform grid. \PGFPlots\ will perform this interpolation automatically: + +\begin{codeexample}[code only] +% non uniform spacing example: the mesh width is provided as first +% part of the specification. +\pgfplotsset{colormap={violetnew} + {[1cm] rgb255(0cm)=(25,25,122) color(1cm)=(white) rgb255(5cm)=(238,140,238)}} +\end{codeexample} +\pgfplotsshowcolormapexample{[1cm] rgb255(0cm)=(25,25,122) color(1cm)=(white) rgb255(5cm)=(238,140,238)} + +\noindent In this last example, the mesh width has been provided explicitly and \PGFPlots\ interpolates the missing grid points on its own. It is an error if the provided positions are no multiple of the mesh width. The |\pgfplotsset| employs the public user interface to create a new color map named `|violetnew|'. + +\noindent The single colors can be separated by semicolons `|;|'. The (optional) length describes how much of the bar is occupied by the interval, it is interpreted relative to the complete length. If the length argument is missing, it is taken to be the last specified length plus the last length difference (the first color defaults to |1cm| in this case). + +Each entry has the form \meta{color model}|(|\meta{length}|)=(|\meta{arguments}|)| where the \meta{length} argument is optional as discussed. The example above means that the left end of the color map shall have RGB components $1,0,0$, indicating $100\%$ red and $0\%$ green and blue. The next entity starts at |1cm| and describes a color with $100\%$ green. The |rgb255| also expects three RGB components, but in the range $[0,255]$. Finally, |gray| specifies a color in parenthesis with the same value for each, R G and B and |color| accesses predefined colors. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + colormap={bw}{gray(0cm)=(0); gray(1cm)=(1)}] + \addplot+[scatter,only marks, + domain=0:8,samples=100] + {exp(x)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +The complete length of a color map is irrelevant: it will be mapped linearly to an internal range anyway (for efficient interpolation). The only requirement is that the left end must be at |0|. + +Available color maps are shown below. + +\end{pgfplotskey} + +\begin{stylekey}{/pgfplots/colormap/hot} + A style which installs the colormap + + |{color(0cm)=(blue); color(1cm)=(yellow); color(2cm)=(orange); color(3cm)=(red)}| + + \pgfplotsshowcolormap{hot} + + This is the preconfigured color map. +\end{stylekey} + +\begin{stylekey}{/pgfplots/colormap/bluered} + A style which installs the colormap + + \{|rgb255(0cm)=(0,0,180); rgb255(1cm)=(0,255,255); rgb255(2cm)=(100,255,0); | + + |rgb255(3cm)=(255,255,0); rgb255(4cm)=(255,0,0); rgb255(5cm)=(128,0,0)|\}, + + \pgfplotsshowcolormap{bluered} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colormap/bluered] + \addplot+[scatter, + scatter src=x,samples=50] + {sin(deg(x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + \paragraph{Remark:} + The style |bluered| (re-)defines the color map and activates it. \TeX\ will be slightly faster if you call |\pgfplotsset{colormap/bluered}| in the preamble (to create the color map once) and use |colormap name=bluered| whenever you need it. This remark holds for every color map style which follows. But you can simply ignore this remark. +\end{stylekey} + +\begin{stylekey}{/pgfplots/colormap/cool} + A style which installs the colormap + + |{rgb255(0cm)=(255,255,255); rgb255(1cm)=(0,128,255); rgb255(2cm)=(255,0,255)}| + + \pgfplotsshowcolormap{cool} +\end{stylekey} + +\begin{stylekey}{/pgfplots/colormap/greenyellow} + A style which installs the colormap + + |{rgb255(0cm)=(0,128,0); rgb255(1cm)=(255,255,0)}| + + \pgfplotsshowcolormap{greenyellow} +\end{stylekey} + +\begin{stylekey}{/pgfplots/colormap/redyellow} + A style which installs the colormap + + |{rgb255(0cm)=(255,0,0); rgb255(1cm)=(255,255,0)}| + + \pgfplotsshowcolormap{redyellow} +\end{stylekey} + +\begin{stylekey}{/pgfplots/colormap/violet} + A style which installs the colormap + + |{rgb255=(25,25,122) color=(white) rgb255=(238,140,238)}| + + \pgfplotsshowcolormap{violet} +\end{stylekey} + +\begin{stylekey}{/pgfplots/colormap/blackwhite} + A style which installs the colormap + + |{gray(0cm)=(0); gray(1cm)=(1)}| + + \pgfplotsshowcolormap{blackwhite} +\end{stylekey} + +\begin{command}{\pgfplotscolormaptoshadingspec\marg{colormap name}\marg{right end size}\marg{\textbackslash macro}} + A command which converts a colormap into a \PGF\ shading's color specification. It can be used in commands like |\pgfdeclare*shading| (see the \PGF\ manual~\cite{tikz} for details). + + The first argument is the name of a (defined) colormap, the second the rightmost dimension of the specification. The result will be stored in \meta{\textbackslash macro}. +\begin{codeexample}[] + % convert `hot' -> \result + \pgfplotscolormaptoshadingspec{hot}{8cm}\result + % define and use a shading in pgf: + \def\tempb{\pgfdeclarehorizontalshading{tempshading}{1cm}}% + % where `\result' is inserted as last argument: + \expandafter\tempb\expandafter{\result}% + \pgfuseshading{tempshading}% +\end{codeexample} +The usage of the result \meta{\textbackslash macro} is a little bit low--level. +\end{command} + +\subsubsection{Cycle Lists -- Options Controlling Linestyles} + +\label{sec:cycle:list}% +\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|. + +There are several possiblities to change the currently active |cycle list|: +\begin{enumerate} + \item Use one of the predefined lists\footnote{In an early version, these lists were called \texttt{\textbackslash coloredplotspeclist} and \texttt{\textbackslash blackwhiteplotspeclist} which appeared to be unnecessarily long, so they have been renamed. The old names are still accepted, however.}, + \begin{itemize} + \item \declareandlabel{color} (from top to bottom) +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + stack plots=y,stack dir=minus, + cycle list name=color] +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + \item \declareandlabel{exotic} (from top to bottom) +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + stack plots=y,stack dir=minus, + cycle list name=exotic] +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + \item \declareandlabel{black white} (from top to bottom) +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + stack plots=y,stack dir=minus, + cycle list name=black white] +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + \item \declareandlabel{mark list} (from top to bottom) +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + stack plots=y,stack dir=minus, + cycle list name=mark list] +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + The |mark list| always employs the current color, but it doesn't define one. + + + \item \declareandlabel{color list} (from top to bottom) +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + stack plots=y,stack dir=minus, + cycle list name=color list] +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + The |cycle list name=color| choice also employs markers whereas |color list| uses \emph{only} colors. + + \item \declareandlabel{linestyles} (from top to bottom) +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + stack plots=y,stack dir=minus, + cycle list name=linestyles] +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + \item \declareandlabel{auto} The |cycle list name=auto| always denotes the most recently used cycle list activated by |cycle list| or |cycle list name|. + \end{itemize} + +The definitions of all predefined cycle lists follow (see the end of this paragraph for a syntax description). +\begin{codeexample}[code only] +\pgfplotscreateplotcyclelist{color}{% + blue,every mark/.append style={fill=blue!80!black},mark=*\\% + red,every mark/.append style={fill=red!80!black},mark=square*\\% + brown!60!black,every mark/.append style={fill=brown!80!black},mark=otimes*\\% + black,mark=star\\% + blue,every mark/.append style={fill=blue!80!black},mark=diamond*\\% + red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\% + brown!60!black,densely dashed,every mark/.append style={ + solid,fill=brown!80!black},mark=square*\\% + black,densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\% + blue,densely dashed,mark=star,every mark/.append style=solid\\% + red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\% +} +\end{codeexample} +\begin{codeexample}[code only] +\pgfplotscreateplotcyclelist{black white}{% + every mark/.append style={fill=gray},mark=*\\% + every mark/.append style={fill=gray},mark=square*\\% + every mark/.append style={fill=gray},mark=otimes*\\% + mark=star\\% + every mark/.append style={fill=gray},mark=diamond*\\% + densely dashed,every mark/.append style={solid,fill=gray},mark=*\\% + densely dashed,every mark/.append style={solid,fill=gray},mark=square*\\% + densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\% + densely dashed,every mark/.append style={solid},mark=star\\% + densely dashed,every mark/.append style={solid,fill=gray},mark=diamond*\\% +} +\end{codeexample} +\begin{codeexample}[code only] +\pgfplotscreateplotcyclelist{exotic}{% + teal,every mark/.append style={fill=teal!80!black},mark=*\\% + orange,every mark/.append style={fill=orange!80!black},mark=square*\\% + cyan!60!black,every mark/.append style={fill=cyan!80!black},mark=otimes*\\% + red!70!white,mark=star\\% + lime!80!black,every mark/.append style={fill=lime},mark=diamond*\\% + red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\% + yellow!60!black,densely dashed, + every mark/.append style={solid,fill=yellow!80!black},mark=square*\\% + black,every mark/.append style={solid,fill=gray},mark=otimes*\\% + blue,densely dashed,mark=star,every mark/.append style=solid\\% + red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\% +} +\end{codeexample} +\begin{codeexample}[code only] +% note that "." is the currently defined Tikz color. +\pgfplotscreateplotcyclelist{mark list}{% + every mark/.append style={fill=.!80!black},mark=*\\% + every mark/.append style={fill=.!80!black},mark=square*\\% + every mark/.append style={fill=.!80!black},mark=triangle*\\% + mark=star\\% + every mark/.append style={fill=.!80!black},mark=diamond*\\% + every mark/.append style={fill=.!80!black},mark=otimes*\\% + mark=|\\% + every mark/.append style={fill=.!80!black},mark=pentagon*\\% + mark=text,text mark=p\\% + mark=text,text mark=a\\% +} +\end{codeexample} +\begin{codeexample}[code only] +\pgfplotscreateplotcyclelist{color list}{% + red,blue,black,yellow,brown,teal,orange,violet,cyan,green!70!black,magenta,gray} +\end{codeexample} +\begin{codeexample}[code only] +\pgfplotscreateplotcyclelist{linestyles}{solid,dashed,dotted} +\end{codeexample} + + \item The second choice for cycle lists is to provide each entry directly as argument to |cycle list|, +\begin{codeexample}[] +\begin{tikzpicture} +\begin{loglogaxis}[cycle list={% + {blue,mark=*}, + {red,mark=square}, + {dashed,mark=o}, + {loosely dotted,mark=+}, + {brown!60!black, + mark options={fill=brown!40}, + mark=otimes*}} +] +\plotcoords +\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} +\end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + (This example list requires |\usetikzlibrary{plotmarks}|). + + The input format is described below in more details. + + \item The last method is to combine 1. and 2.: Define named cycle lists in the preamble and use them with `|cycle list name|': +\begin{command}{\pgfplotscreateplotcyclelist\marg{name}\marg{list}}% +\end{command} +\begin{codeexample}[code only] +\pgfplotscreateplotcyclelist{mylist}{% + {blue,mark=*}, + {red,mark=square}, + {dashed,mark=o}, + {loosely dotted,mark=+}, + {brown!60!black,mark options={fill=brown!40},mark=otimes*}} +... +\begin{axis}[cycle list name=mylist] + ... +\end{axis} +\end{codeexample} +\end{enumerate} + +\paragraph{The format of \marg{list}:} The argument \meta{list} is usually a comma separated list of lists of style keys like colors, line styles, marker types and marker styles. This ``comma list of comma lists'' structure requires to encapsulate the inner list using curly braces: +\begin{codeexample}[code only] +\pgfplotscreateplotcyclelist{mylist}{% + {blue,mark=*}, + {red,mark=square}, + {dashed,mark=o}, + {loosely dotted,mark=+}, + {brown!60!black,mark options={fill=brown!40},mark=otimes*}} +\end{codeexample} +Alternatively, one can terminate the inner lists (i.e.\ those for one single plot) with `|\\|': +\begin{codeexample}[code only] +\begin{axis}[cycle list={% + blue,mark=*\\% + red,mark=square\\% + dashed,mark=o\\% + loosely dotted,mark=+\\% + brown!60!black,mark options={fill=brown!40},mark=otimes*\\% +} +] +... +\end{axis} +\end{codeexample} +In this case, the \emph{last} entry also needs a terminating `|\\|', but one can omit braces around the single entries. + +\paragraph{Remark:} It is possible to call |\pgfplotsset{cycle list=|\marg{a list}|}| or |cycle list name| \emph{between} plots. Such a setting remains effective until the end of the current \TeX\ group (that means curly braces). Every |\addplot| command queries the |cycle list| using the plot index; it doesn't hurt if |cycle list|s have changed in the meantime. +\end{pgfplotskeylist} + +\begin{pgfplotskey}{cycle multi list=\meta{list 1}\texttt{\textbackslash nextlist}\meta{list 2}\texttt{\textbackslash nextlist}$\dotsb$} + Allows to supply more than one |cycle list| in a way such that each one contributes to the plot style. This is probably best explained using an example: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + cycle multi list={ + red,blue\nextlist + solid,{dotted,mark options={solid}}\nextlist + mark=*,mark=x,mark=o + }, + samples=3, + legend entries={0,...,20}, + legend pos=outer north east +] + \addplot {x}; + \addplot {x-1}; + \addplot {x-2}; + \addplot {x-3}; + \addplot {x-4}; + \addplot {x-5}; + \addplot {x-6}; + \addplot {x-7}; + \addplot {x-8}; + \addplot {x-9}; + \addplot {x-10}; + \addplot {x-11}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + \noindent The provided |cycle multi list| consists of three lists. The style for a single plot is made up using elements of each of the three lists: the first plot has style |red,solid,mark=*|, the second has |red,solid,mark=x|, the third has |red,solid,mark=o|. The fourth plot restarts the third list and uses the next one of list $2$: it has |red,dotted,mark options={solid},mark=*| and so on. + + The last list will always be advanced for a new plot. The list before the last (in our case the second list) will be advanced after the last one has been reset. In other words: |cycle multi list| allows a composition of different |cycle list| in a lexicographical way\footnote{For those who prefer formulars: The plot with index $0 \le i < N$ will use cycle list offsets $i_0,i_1,\dotsc,i_k$, $0 \le i_m < N_m$ where $k$ is the number of arguments provided to \texttt{cycle multi list} and $N_m$ is the number of elements in the $m$th cycle list. The offsets $i_m$ are computed in a loop {\ttfamily \{ int tmp=i; for( int m=k-1; m>=0; m=m-1 ) \{ i\_m = tmp\%N\_m; tmp = tmp/N\_m; \}\}}.}. + + The argument for |cycle multi list| is a sequence of arguments as they would have been provided for |cycle list|, separated by \declareandlabel{\nextlist}. In addition to providing a new cycle list, the \meta{list $i$} elements can also denote |cycle list name| values (including the special |auto| cycle list which is the most recently assigned |cycle list| or |cycle list name|). The final |\nextlist| is optional. + + The list in our example above could have been written as +\begin{codeexample}[code only] +\begin{axis}[ + cycle multi list={ + red\\blue\\\nextlist + solid\\dotted,mark options={solid}\\\nextlist + mark=*\\mark=x\\mark=o\\ + }] +\end{codeexample} +\noindent as well (note the terminating |\\| commands!). + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title={Cycle color between successive plots, then marks}, + cycle multi list={ + mark list\nextlist + blue,red% + }, + samples=3, + legend entries={0,...,20}, + legend pos=outer north east +] + \addplot {x}; + \addplot {x-1}; + \addplot {x-2}; + \addplot {x-3}; + \addplot {x-4}; + \addplot {x-5}; + \addplot {x-6}; + \addplot {x-7}; + \addplot {x-8}; + \addplot {x-9}; + \addplot {x-10}; + \addplot {x-11}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + + \paragraph{Using Sub--Lists} The \meta{list $i$} entry can also contain just the first $n$ elements of an already known cycle list name using the syntax |[|\meta{number}| of]|\meta{cycle list name}. For example |[2 of]mark list| will use the first $2$ elements of |mark list|: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title={Cycle 2 marks between successive plots, then colors}, + cycle multi list={% + blue,red\nextlist + [2 of]mark list + }, + samples=3, + legend entries={0,...,20}, + legend pos=outer north east +] + \addplot {x}; + \addplot {x-1}; + \addplot {x-2}; + \addplot {x-3}; + \addplot {x-4}; + \addplot {x-5}; + \addplot {x-6}; + \addplot {x-7}; + \addplot {x-8}; + \addplot {x-9}; + \addplot {x-10}; + \addplot {x-11}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\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. + +\pgfplotsexpensiveexample +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + axis background/.style={fill=blue!10}] + + \addplot3[surf,y domain=0:1] + {sin(deg(x)) * y*(1-y)}; + + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Please note that legends are filled with white in the default configuration. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{semilogyaxis}[ + axis background/.style={ + shade,top color=gray,bottom color=white}, + legend style={fill=white}] + + \addplot {exp(-x)}; + \addplot {exp(-4*x)}; + \legend{$e^{-x}$,$e^{-4x}$} + \end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} + Details about |fill| and |shade| can be found in the \Tikz\ manual, \cite{tikz}. +\end{pgfplotskey} + + +\subsection{Providing Color Data - Point Meta} +\label{pgfplots:point:meta} +\PGFPlots\ provides features which modify plots depending on a special coordinate, the ``point meta data''. For example, scatter plots may vary marker colors, size or appearance depending on this special data. Surface and mesh plots are another example: here, the color of a surface patch (or mesh part) depends on ``point meta''. + +The common idea idea is to tell \PGFPlots\ how to get this data. It is not necessary to provide data explicitly -- in many cases, the data which is used to color surface patches or marker colors is the plot's $y$ or $z$ coordinate. The method used to tell \PGFPlots\ where to find ``point meta data'' is the |point meta| key. + +A further common idea is the use of color maps: if the point meta data is in the interval $[m_{\text{min}},m_{\text{max}}]$, the point meta coordinate $m = m_{\text{min}}$ will get the lowest color provided by the color map while $m=m_{\text{max}}$ will get the highest color provided by the color map. Any coordinate between this values will be mapped linearly: for example, the mean $m = 1/2 (m_{\text{max}} + m_{\text{min}})$ will get the middle color of the color map. This is why ``point meta'' is sometimes called ``color data''. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[colorbar] + \addplot[mesh,point meta=y,thick] {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{pgfplotskey}{point meta=\mchoice{none,\meta{expression},x,y,z,f(x),explicit,explicit symbolic} (initially none)} + \label{pgfplots:pointmeta} + The |point meta| key tells \PGFPlots\ where to get the special point meta data. Please note that |point meta| and |scatter src| is actually the same -- |scatter src| is an alias for |point meta|. Thus, the summary provided for |scatter src| on page~\pageref{pgfplots:scatter:src} covers the same topics. However, the main reference for |point meta| is here. + + \begin{description} + \item[\declaretext{none}] The initial choice |none| disables point meta data, resulting in no computational work. Any other choice will activate the computation of upper and lower ranges for point meta data, i.e.\ the computation of $[m_{\text{min}},m_{\text{max}}]$. + + \item[\declaretext{x}] The choice |x| uses the already available $x$ coordinates as point meta data. This does always refer to the \emph{final} $x$ coordinates after any user transformations, logarithms, stacked plot computations etc.\ have been applied. Consider using |rawx| if you need the unprocessed coordinate value here. + + \item[\declaretext{y}] + \item[\declaretext{z}] + The choices |y| and |z| are similar: they use the $y$ or $z$ coordinates respectively as point meta data. Consequently, these three choices do \emph{not} need any extra data. As for |x|, there are math constants |rawy| and |rawz| which yield the unprocessed $y$ and $z$ value, respectively. + + \item[\declaretext{f(x)}] This will use the last available coordinate, in other words: it is the same as |y| for two dimensional plots and |z| for three dimensional ones. + + \item[\declaretext{explicit}] This choice tells \PGFPlots\ to expect \emph{numerical} point meta data which is provided explicitly in the coordinate input streams. This data will be transformed linearly into the current color map as it has been motivated above. + + How point meta data is provided for |plot coordinates|, |plot table| and the other input methods is described in all detail in section~\ref{pgfplots:providing:input} -- but we provide small examples here to summarize the possibilities: +\begin{codeexample}[code only] +% for 'coordinates': +% provide color data explicitly using [<data>] +% behind coordinates: +\addplot+[point meta=explicit] + coordinates { + (0,0) [1.0e10] + (1,2) [1.1e10] + (2,3) [1.2e10] + (3,4) [1.3e10] + % ... + }; +\end{codeexample} + +\begin{codeexample}[code only] +% for 'table': +% Assumes a datafile.dat like +% xcolname ycolname colordata +% 0 0 0.001 +% 1 2 0.3 +% 2 2.1 0.4 +% 3 3 0.5 +% ... +% the file may have more columns. +\addplot+[point meta=explicit] + table[x=xcolname,y=ycolname,meta=colordata] + {datafile.dat}; +% or, equivalently (perhaps a little bit slower): +\addplot+[point meta=\thisrow{colordata}] + table[x=xcolname,y=ycolname] + {datafile.dat}; +\end{codeexample} + +\begin{codeexample}[code only] +% for 'file': +% Assumes a datafile.dat like +% 0 0 0.001 +% 1 2 0.3 +% 2 2.1 0.4 +% 3 3 0.5 +% ... +% the first three columns will be used here as x,y and meta, +% resp. +\addplot+[point meta=explicit] + file {datafile.dat}; +\end{codeexample} + +\begin{codeexample}[code only] +% 'table' using expressions which may depend on all +% columns: +% Assumes a datafile.dat like +% xcolname ycolname anything othercol +% 0 0 4 15 +% 1 2 5 20 +% 2 2.1 8 30 +% 3 3 42 40 +% ... +% the file may have more columns. +\addplot+[point meta={0.5*(\thisrow{anything} + sqrt(\thisrow{othercol}))}] + table[x=xcolname,y=ycolname] + {datafile.dat}; +\end{codeexample} + Thus, there are several methods to provide point meta (color data). The key for the choice |explicit| is that some data is provided explicitly -- although |point meta| doesn't know how. The data is expected to be of numerical type and is mapped linearly into the range $[0,1000]$ (maybe for use in the current color map). + + \item[\declaretext{explicit symbolic}] The choice |explicit symbolic| is very similar to |explicit| in that it expects extra data by the coordinate input routines. However, |explicit symbolic| does not necessarily expect numerical data: you can provide any sort of symbols. One might provide a set of styles, one for each class in a scatter plot. This is realised using |scatter/classes|, see page~\pageref{pgfplots:scatterclasses}. Input data is provided in the same fashion as mentioned above for the choice |explicit|. + + 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}). + + The \meta{expression} is checked after the other possible choices have already been evaluated. In other words, the statement + + |point meta=explicit, point meta=meta^2+3| + + will evaluate the expression with |meta| set to whatever data has been provided explicitly. + \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 + \[ \phi\colon [m_{\text{min}},m_{\text{max}}] \to [0,1000] \] + with + \[ \phi(m) = \frac{m - m_{\text{min}}} {1000} \] + such that $\phi(m_{\text{min}}) = 0$ and $\phi(m_{\text{max}})=1000$. The value $1000$ is -- per convention -- the upper limit of all color maps. Now, if a coordinate (or edge/face) has the point meta data $m$, its color will be determined using $\phi(m)$: it is the color at $\phi(m)$\textperthousand\ of the current color map. + + This transformation depends on the interval $[m_{\text{min}},m_{\text{max}}]$ which, in turn, can be modified using the keys |point meta rel|, |point meta min| and |point meta max| described below. + + The untransformed point meta data is available in the macro \declareandlabel{\pgfplotspointmeta} (only in the correct context, for example the scatter plot styles or the |scatter/@pre marker code| interface). This macro contains a low level floating point number (unless it is non-parsed string data). The transformed data will be available in the macro \declareandlabel{\pgfplotspointmetatransformed} and is in fixed point representation. It is expected to be in the range $[0,1000]$. + +\end{pgfplotskey} + +\begin{pgfplotskey}{set point meta if empty=\marg{point meta source}} + Sets |point meta=|\meta{point meta source}, but only if |point meta=none| currently. This is used for |scatter|, |mesh| and |surf| with |set point meta if empty=f(x)|. +\end{pgfplotskey} + +\begin{pgfplotskey}{point meta rel=\mchoice{axis wide,per plot} (initially axis wide)} + As already explained in the documentation for |point meta|, one application for point meta data is to determine colors using the current color map and a linear map from point meta data into the current color map. The question is how this linear map is computed. + + The key |point meta rel| configures whether the interval of all point meta coordinates, $[m_{\text{min}},m_{\text{max}}]$ is computed as maximum over all plots in the complete axis (the choice \declaretext{axis wide}) or only for one particular plot (the choice \declaretext{per plot}). + +\message{Overfull hbox is ok.}% +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + title=Axis wide color mapping, + colorbar, + samples=50,point meta rel=axis wide, + point meta=y] + + \addplot[mesh,thick] {sin(deg(x))}; + \addplot[mesh,thick] {3*tanh(x)}; + \end{axis} +\end{tikzpicture} +~ +\begin{tikzpicture} + \begin{axis}[ + title=Per Plot color mapping, + colorbar, + samples=50, + point meta rel=per plot, + point meta=y] + + \addplot[mesh,thick] {sin(deg(x))}; + \addplot[mesh,thick] {3*tanh(x)}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + +\begin{pgfplotskeylist}{point meta min=\marg{number},point meta max=\marg{number}} + These keys allow to define the range required for the linear map of point meta data into the range $[0,1000]$ (for example, for current maps) explicitly. This is necessary if the same mapping shall be used for more than one axis. + + \paragraph{Remarks about special cases:} + \begin{itemize} + \item It is possible to provide limits partially; in this case, only the missing limit will be computed. + \item If point meta data falls outside of these limits, the linear transformation is still well defined which is acceptable (unless the interval is of zero length). However, color data can't be outside of these limits, so color bars perform a truncation. + \item This key can be provided for single plots as well as for the complete axis (or for both). + \item If meta limits are provided for a single plot, these limits may also contribute to the axis wide meta interval. + \end{itemize} +\end{pgfplotskeylist} + +\begin{pgfplotskey}{colormap access=\mchoice{map,direct} (initially map)} + This key configures how point meta data is used to determine colors from a color map. The initial configuration |map| performs the linear mapping operation explained above. The choice |direct| does not perform any transformation; it takes the point meta as integer indizes into the current color map. + + Consequently, there is no interpolation between colors in the color map, there will only be as many colors as the color map contains explicitly. + + \paragraph{Some more details:} + \begin{itemize} + \item If there are $m$ colors in the color map and the color data falls outside of $[0,m-1]$, it will be pruned to either the first or the last color. + \item If color data is a real number, it will be truncated to the next smaller integer. + \item + This key does not work for |shader=interp| (note that this shader will always interpolate in the color map). + \end{itemize} + \paragraph{Attention:} This feature is experimental, I did not have time to test it. +\end{pgfplotskey} + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex new file mode 100644 index 00000000000..f31ef4b925f --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex @@ -0,0 +1,179 @@ + + +\subsection{Miscellaneous Options} +\label{pgfplots:misc} + +\begin{pgfplotskey}{disablelogfilter=\mchoice{true,false} (initally false, default true)} +Disables numerical evaluation of $\log(x)$ in \TeX. If you specify this option, any plot coordinates and tick positions must be provided as $\log(x)$ instead of $x$. This may be faster and -- possibly -- more accurate than the numerical log. The current implementation of $\log(x)$ normalizes~$x$ to $m\cdot 10^e$ and computes +\[ \log(x) = \log(m) + e \log(10) \] +where $y = \log(m)$ is computed with a newton method applied to $\exp(y) - m$. The normalization involves string parsing without \TeX-registers. You can savely evaluate $\log(1\cdot 10^{-7})$ although \TeX-registers would produce an underflow for such small numbers. +\end{pgfplotskey} + +\label{sec:disabledatascaling}% +\begin{pgfplotskey}{disabledatascaling=\mchoice{true,false} (initally false, default true)} +\index{Accuracy!Data Transformation}% +\index{Errors!dimension too large}% +Disables internal re-scaling of input data. Normally, every input data like plot coordinates, tick positions or whatever, are parsed without using \TeX's limited number precision. Then, a transformation like + \[ T(x) = 10^{q-m} \cdot x - a \] +is applied to every input coordinate/position where $m$ is ``the order of $x$'' base~$10$. Example: $x=1234 = 1.234\cdot 10^3$ has order~$m=4$ while $x=0.001234 = 1.234\cdot 10^{-3}$ has order $m=-2$. The parameter~$q$ is the order of the axis' width/height. + +The \textbf{effect} of the transformation is that your plot coordinates can be of \emph{arbitrary magnitude} like $0.0000001$ and $0.0000004$. For these two coordinates, \PGFPlots\ will use 100pt and 400pt internally. The transformation is quit fast since it relies only on period shifts. This scaling allows precision beyond \TeX's capabilities. +%\footnote{Please note that while plot coordinates can be of quite large magnitude like $10^12$ or $10^{-9}$, \PGFPlots\ still uses \TeX-registers internally (the math parser of \PGF). If your axis interval is $[1234567.8, 1234567.9]$ or something like that, }. + +The option ``|disabledatascaling|'' disables this data transformation. This has two consequences: first, coordinate expressions like \parg{{\normalfont\texttt{axis cs:}}x,y} have the same effect like \parg{x,y}, no re-scaling is applied. Second, coordinates are restricted to what \TeX\ can handle\footnote{Please note that the axis' scaling requires to compute $1/( x_\text{max} - x_{\text{min}} )$. The option \protect\pgfmanualpdfref{disabledatascaling}{\texttt{disabledatascaling}} may lead to overflow or underflow in this context, so use it with care! Normally, the data scale transformation avoids this problem.}. + +So far, the data scale transformation applies only to normal axis (logarithmic scales do not need it). +\end{pgfplotskey} + + +\begin{pgfplotskey}{execute at begin plot=\marg{commands}} +This axis option allows to invoke \marg{commands} at the beginning of each |\addplot| command. The argument \marg{commands} can be any \TeX\ content. + +You may use this in conjunction with |x filter=...| to reset any counters or whatever. An example would be to change every $4$th coordinate. +\end{pgfplotskey} + +\begin{pgfplotskey}{execute at end plot=\marg{commands}} +This axis option allows to invoke \marg{commands} after each |\addplot| command. The argument \marg{commands} can be any \TeX\ content. +\end{pgfplotskey} + +\begin{pgfplotskey}{forget plot=\marg{true,false} (initially false)} +\label{pgfplots:forgetplot} + Allows to include plots which are not remembered for legend entries, which do not increase the number of plots and which are not considered for cycle lists. + + A forgotten plot can be some sort of decoration which has a separate style and does not influence the axis state, although it is processed as any other plot. + Provide this option to |\addplot| as in the following example. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[ + % some descriptions: + table/x=Basis, + table/y={L2/r}, + xlabel=Degrees of Freedom, + ylabel=relative Error, + title=New Experiments (old in gray), + legend entries={$e_1$,$e_2$,$e_3$} + ] + \addplot[black!15,forget plot] + table {plotdata/oldexperiment1.dat}; + \addplot[black!15,forget plot] + table {plotdata/oldexperiment2.dat}; + \addplot[black!15,forget plot] + table {plotdata/oldexperiment3.dat}; + \addplot table {plotdata/newexperiment1.dat}; + \addplot table {plotdata/newexperiment2.dat}; + \addplot table {plotdata/newexperiment3.dat}; + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + Since forgotten plots won't increase the plot index, they will use the same |cycle list| entry as following plots. + + The style |every forget plot| can be used to configure styles for each such plot: +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[ + forget plot style={opacity=0.2}, + % same as above: + table/x=Basis, + table/y={L2/r}, + xlabel=Degrees of Freedom, + ylabel=relative Error, + title=New Experiments (old in transparent), + legend entries={$e_1$,$e_2$,$e_3$}, + ] + \foreach \exp in {1,2,3} { + \addplot+[forget plot] + table {plotdata/oldexperiment\exp.dat}; + \addplot table {plotdata/newexperiment\exp.dat}; + } + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + \noindent Here, the |\addplot+| command means we are using the same |cycle list| as the following plot and |forget plot style| modifies |every forget style| and yields transparency of the ``old experiments''. + + Please note that |every plot no |\meta{index} styles are not applicable here. + + A forgotten plot will be stacked normally if |stack plots| is enabled! +\end{pgfplotskey} + +\begin{pgfplotscodekey}{before end axis} +Allows to insert \marg{commands} just before the axis is ended. This option takes effect inside of the clipped area. +\begin{codeexample}[] +\pgfplotsset{every axis/.append style={ + before end axis/.code={ + \fill[red] (axis cs:1,10) circle(5pt); + \node at (axis cs:-4,10) + {\large This text has been inserted + using \texttt{before end axis}.}; + }}} +\begin{tikzpicture} + \begin{axis} + \addplot {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotscodekey} + +\begin{pgfplotscodekey}{after end axis} +Allows to insert \marg{commands} right after the end of the clipped drawing commands. While |befor end axis| has the same effect as if \marg{commands} had been placed inside of your axis, |after end axis| allows to access axis coordinates without being clipped. +\begin{codeexample}[] +\pgfplotsset{every axis/.append style={ + after end axis/.code={ + \fill[red] (axis cs:1,10) circle(5pt); + \node at (axis cs:-4,10) + {\large This text has been inserted using \texttt{after end axis}.}; + }}} +\begin{tikzpicture} + \begin{axis} + \addplot {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotscodekey} + +\begin{pgfplotskey}{clip marker paths=\mchoice{true,false} (initially false)} + The initial choice |clip marker paths=false| causes markers to be drawn \emph{after} the clipped region. Only their positions will be clipped. As a consequence, markers will be drawn completely, or not at all. The value |clip marker paths=true| is here for backwards compatibility: it does not introduce special marker treatment, so markers may be drawn partially if they are close to the clipping boundary\footnote{Please note that clipped marker paths may be slightly faster during \TeX\ compilation.}. +\end{pgfplotskey} + +\begin{pgfplotskey}{clip=\mchoice{true,false} (initially true)} + Whether any paths inside an axis shall be clipped. +\end{pgfplotskey} + +\begin{pgfplotskey}{axis on top=\mchoice{true,false} (initially false)} + If set to |true|, axis lines, ticks, tick labels and grid lines will be drawn on top of plot graphics. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + axis on top=true, + axis x line=middle, + axis y line=middle] + \addplot+[fill] {x^3} \closedcycle; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + axis on top=false, + axis x line=middle, + axis y line=middle] + \addplot+[fill] {x^3} \closedcycle; + \end{axis} +\end{tikzpicture} +\end{codeexample} +Please note that this feature does not affect plot marks. I think it looks unfamiliar if plot marks are crossed by axis descriptions. +\end{pgfplotskey} + +\begin{key}{/pgf/fpu=\marg{true,false} (initially true)} +\index{Precision} + This key activates or deactivates the floating point unit. If it is disabled (|false|), the core \PGF\ math engine written by Mark Wibrow and Till Tantau will be used for |plot expression|. + However, this engine has been written to produce graphics and is not suitable for scientific computing. It is limited to fixed point numbers in the range $\pm 16384.00000$. + + If the |fpu| is enabled (|true|, the initial configuration) the high-precision floating point library of \PGF\ written by Christian Feuers\"anger will be used. It offers the full range of IEEE double precision computing in \TeX. This FPU is also part of \PGFPlotstable, and it is activated by default for |create col/expr| and all other predefined mathematical methods. + + Use +\begin{codeexample}[code only] +\pgfkeys{/pgf/fpu=false} +\end{codeexample} + \noindent in order to de-activate the extended precision. If you prefer using the |fp| (fixed point) package, possibly combined with Mark Wibrows corresponding \PGF\ library, the |fpu| will be deactivated automatically. Please note, however, that |fp| has a smaller data range (about $\pm 10^{17}$) and may be slower. +\end{key} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.numberformatting.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.numberformatting.tex new file mode 100644 index 00000000000..8eec38ea994 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.numberformatting.tex @@ -0,0 +1,154 @@ + +\subsection{Number Formatting Options} +\label{sec:number:printing}% +\PGFPlots\ typeset tick labels rounded to given precision and in configurable number formats. The command to do so is |\pgfmathprintnumber|; it uses the current set of number formatting options. + +These options are described in all detail in the manual for \PGFPlotstable, which comes with \PGFPlots. Please refer to that manual. + +\begin{command}{\pgfmathprintnumber\marg{x}} +Generates pretty-printed output for the (real) number \marg{x}. The input number \marg{x} is parsed using |\pgfmathfloatparsenumber| which allows arbitrary precision. + +Numbers are typeset in math mode using the current set of number printing options, see below. Optional arguments can also be provided using |\pgfmathprintnumber[|\meta{options}|]|\marg{x}. + +Please refer to the manual of \PGFPlotstable\ (shipped with this package) for details about the number options. +\end{command} + +\label{sec:identify:minor:log}% +\begin{pgfplotskey}{log identify minor tick positions=\mchoice{true,false} (initially false)} +Set this to |true| if you want to identify log--plot tick labels at positions +\[ i \cdot 10^j \] +with $i \in \{2,3,4,5,6,7,8,9\},\, j \in \Z$. This may be valueable in conjunction with the `|extra x ticks|' and `|extra y ticks|' options. +\begin{codeexample}[] +\begin{tikzpicture}% +\begin{loglogaxis} + [title=Standard options, + width=6cm] +\addplot coordinates { + (1e-2,10) + (3e-2,100) + (6e-2,200) +}; +\end{loglogaxis} +\end{tikzpicture}% +\end{codeexample} + +\begin{codeexample}[] +\pgfplotsset{every axis/.append style={% + width=6cm, + xmin=7e-3,xmax=7e-2, + extra x ticks={3e-2,6e-2}, + extra x tick style={major tick length=0pt,font=\footnotesize} +}}% + +\begin{tikzpicture}% + \begin{loglogaxis}[ + xtick={1e-2}, + title=with minor tick identification, + extra x tick style={ + log identify minor tick positions=true}] + \addplot coordinates { + (1e-2,10) + (3e-2,100) + (6e-2,200) + }; + \end{loglogaxis} +\end{tikzpicture}% + +\begin{tikzpicture}% + \begin{loglogaxis}[ + xtick={1e-2}, + title=without minor tick identification, + extra x tick style={ + log identify minor tick positions=false}] + \addplot coordinates { + (1e-2,10) + (3e-2,100) + (6e-2,200) + }; + \end{loglogaxis}% +\end{tikzpicture}% +\end{codeexample} + This key is set by the default styles for extra ticks. +\end{pgfplotskey} + +\begin{pgfplotscodekey}{log number format code} +Provides \TeX-code to generate log plot tick labels. Argument `|#1|' is the (natural) logarithm of the tick position. +The default implementation invokes |log base 10 number format code| after it changed the log basis to~$10$. It also checks the other log plot options. + +This key will have a different meaning when the log basis has been chosen explicitly, see the |log basis x| key. +\end{pgfplotscodekey} + + +\begin{pgfplotscodekey}{log base 10 number format code} +Allows to change the overall appearance of base 10 log plot tick labels. The default is +\begin{codeexample}[code only] +\pgfplotsset{ + log base 10 number format code/.code={$10^{\pgfmathprintnumber{#1}}$} +} +\end{codeexample} +where the `|log plot exponent style|' allows to change number formatting options. +\end{pgfplotscodekey} + +\begin{pgfplotscodekey}{log number format basis} + This part of the representation routines for log ticks in \emph{arbitrary} basis (see the |log basis x| key). It is used instead of the key above if the log basis has been changed. The first supplied argument is the log basis, the second the exponent. The initial configuration is +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/log number format basis/.code 2 args={$#1^{\pgfmathprintnumber{#2}}$} +} +\end{codeexample} +\end{pgfplotscodekey} + +\begin{pgfplotskey}{log plot exponent style=\marg{key-value-list}} +Allows to configure the number format of log plot exponents. This style is installed just before `|log base 10 number format code|' will be invoked. Please note that this style will be installed within the default code for `|log number format code|'. +\begin{codeexample}[] +\pgfplotsset{ + samples=15, + width=7cm, + xlabel=$x$, + ylabel=$f(x)$, + extra y ticks={45}, + legend style={at={(0.03,0.97)}, + anchor=north west}} + +\begin{tikzpicture} +\begin{semilogyaxis}[ + log plot exponent style/.style={ + /pgf/number format/fixed zerofill, + /pgf/number format/precision=1}, + domain=-5:10] + + \addplot {exp(x)}; + \addplot {exp(2*x)}; + + \legend{$e^x$,$e^{2x}$} +\end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\pgfplotsset{ + samples=15, + width=7cm, + xlabel=$x$, + ylabel=$f(x)$, + extra y ticks={45}, + legend style={at={(0.03,0.97)}, + anchor=north west}} + +\begin{tikzpicture} +\begin{semilogyaxis}[ + log plot exponent style/.style={ + /pgf/number format/fixed, + /pgf/number format/use comma, + /pgf/number format/precision=2}, + domain=-5:10] + + \addplot {exp(x)}; + \addplot {exp(2*x)}; + + \legend{$e^x$,$e^{2x}$} +\end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex new file mode 100644 index 00000000000..fe8d58ad432 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.preliminaryoptions.tex @@ -0,0 +1,114 @@ + +\subsection{About Options: Preliminaries} +\PGFPlots\ knowns a whole lot of key--value options which can be (re-)defined to activate desired features or modified to apply some fine tuning. + +\noindent Most keys can be used like +\begin{codeexample}[code only] +\begin{tikzpicture} +\begin{axis}[key=value,key2=value2] +... +\end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent which changes them for the complete axis. Some keys can be changed for each plot: +\begin{codeexample}[code only] +\begin{tikzpicture} +\begin{axis} +\addplot[key=value,key2=value2] ... ; +\addplot+[key=value,key2=value2] ... ; % keeps the keys which would have been used by default +\end{axis} +\end{tikzpicture} +\end{codeexample} + +The basic engine to manage key--value pairs is |pgfkeys| which is part of \pgfname. This engine always has a key name and a key ``path'', which is somehow similar to file name and directory of files. The common ``directory'' (key path) of \PGFPlots\ is `|/pgfplots/|'. Although the key definitions below provide this full path, it is always (well, almost always) enough to skipt this prefix -- \PGFPlots\ uses it automatically. The same holds for the prefixes `|/tikz/|' which are common for all \Tikz\ drawing options and `|/pgf/|' which are for the (more or less) low--level commands of \pgfname. All these prefixes can be omitted. + +One important concept is the concept of styles. A style is a key which contains one or more other keys. It can be redefined or modified until it is actually used by the internal routines. Each single component of \Tikz\ and \PGFPlots\ can be configured with styles. + +For example, +\begin{codeexample}[code only] +\pgfplotsset{every axis/.append style={line width=1pt}} +\end{codeexample} +\noindent +sets the line width for every axis to |1pt|. + +There are several other styles predefined to modify the appearance, see section~\ref{sec:styles}. + +\begin{command}{\pgfplotsset\marg{key-value-list}} + Defines or sets all options in \marg{key-value-list}. + + It is a shortcut for |\pgfqkeys{/pgfplots}|\marg{key-value-list}, that means it inserts the prefix |/pgfplots| to any option which has no full path. + + This command can be used to define default options for the complete document or a part of the document. For example, +\begin{codeexample}[code only] +\pgfplotsset{ + cycle list={% + {red, mark=*}, {blue,mark=*}, + {red, mark=x}, {blue,mark=x}, + {red, mark=square*}, {blue,mark=square*}, + {red, mark=triangle*}, {blue,mark=triangle*}, + {red, mark=diamond*}, {blue,mark=diamond*}, + {red, mark=pentagon*}, {blue,mark=pentagon*} + }, + legend style={ + at={(0.5,-0.2)}, + anchor=north, + legend columns=2, + cells={anchor=west}, + font=\footnotesize, + rounded corners=2pt, + }, + xlabel=$x$,ylabel=$f(x)$ +} +\end{codeexample} + can be used to set document--wise styles for line specifications, the legend's style and axis labels. + + You can also define new styles (collections of key--value--pairs) with |/.style| and |/.append style|. +\begin{codeexample}[code only] +\pgfplotsset{ + My Style 1/.style={xlabel=$x$, legend entries={1,2,3} }, + My Style 2/.style={xlabel=$X$, legend entries={4,5,6} } +} +\end{codeexample} + The |/.style| and |/.append style| key handlers are described in section~\ref{sec:styles} in more detail. +\end{command} + +\begin{handler}{{.code}=\marg{\TeX\ code}} + Occasionally, the \PGFPlots\ user interface offers to replace parts of its routines. This is accomplished using so called ``code keys''. What it means is to replace the original key and its behavior with new \marg{\TeX\ code}. Inside of \marg{\TeX\ code}, any command can be used. Furthermore, the |#1| pattern will be the argument provided to the key. + +\begin{codeexample}[] +\pgfplotsset{ + My Code/.code={I've been invoked with `#1'}} +\pgfplotsset{My Code={this here}} +\end{codeexample} + The example defines a (new) key named |My Code|. Essentially, it is nothing else but a |\newcommand|, plugged into the key-value interface. The second statement ``invokes'' the code key. +\end{handler} + +\begin{handler}{{.code 2 args}=\marg{\TeX\ code}} + As |/.code|, but this handler defines a key which accepts two arguments. When the so defined key is used, the two arguments are available as |#1| and |#2|. +\end{handler} + +\begin{handler}{{.cd}} + Each key has a fully qualified name with a (long) prefix, like |/pgfplots/xmin|. However, if the ``current directory'' is |/pgfplots|, it suffices to write just |xmin|. The |/.cd| key handler changes the ``current directory'' in this way. + + The prefixes |/tikz/| and |/pgfplots/| are checked automatically for any argument provided to |\begin{axis}|\oarg{options} or |\addplot|. So, you won't need to worry about them, just leave them away -- and look closer in case the package doesn't identify the option. +\end{handler} + +\subsubsection{Pgfplots Options and \Tikz\ Options} +This section is more or less technical and can be skipped unless one really wants to know more about this topic. + +\Tikz\ options and \PGFPlots\ options can be mixed inside of the axis arguments and in any of the associated styles. For example, +\begin{codeexample}[code only] +\pgfplotsset{every axis legend/.append style={ + legend columns=3,font=\Large}} +\end{codeexample} +\noindent +assigns the `|legend columns|' option (a \PGFPlots\ option) and uses `|font|' for drawing the legend (a \Tikz\ option). The point is: |legend columns| needs to be known \emph{before} the legend is typeset whereas |font| needs to be active when the legend is typeset. \PGFPlots\ sorts out any key dependencies automatically: + +The axis environments will process any known \PGFPlots\ options, and all `|every|'--styles will be parsed for \PGFPlots\ options. Every unknown option is supposed to be a \Tikz\ option and will be forward to the associated \Tikz\ drawing commands. For example, the `|font=\Large|' above will be used as argument to the legend matrix, and the `|font=\Large|' argument in +\begin{codeexample}[code only] +\pgfplotsset{every axis label/.append style={ + ylabel=Error,xlabel=Dof,font=\Large}} +\end{codeexample} +will be used in the nodes for axis labels (but not the axis title, for example). + +It is an error if you assign incompatible options to axis labels, for example `|xmin|' and `|xmax|' can't be set inside of `|every axis label|'. diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex new file mode 100644 index 00000000000..8e25d5a7b03 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex @@ -0,0 +1,190 @@ + +\subsection{Scaling Options} + +\begin{pgfplotskey}{width=\marg{dimen}} +Sets the width of the final picture to \marg{dimen}. If no |height| is specified, scaling will respect aspect ratios. + +\paragraph{Remarks:} +\begin{itemize} + \item The scaling only affects the width of one unit in $x$-direction or the height for one unit in $y$-direction. Axis labels and tick labels won't be resized, but their size is used to determine the axis scaling. + + \item You can use the |scale=|\marg{number} option, +\begin{codeexample}[code only] +\begin{tikzpicture}[scale=2] +\begin{axis} +... +\end{axis} +\end{tikzpicture} +\end{codeexample} + to scale the complete picture. + + \item The \Tikz-options |x| and |y| which set the unit dimensions in $x$ and $y$ directions can be specified as arguments to |\begin{axis}[x=1.5cm,y=2cm]| if needed (see below). These settings override the |width| and |height| options. + + \item You can also force a fixed width/height of the axis (without looking at labels) with +\begin{codeexample}[code only] +\begin{tikzpicture} +\begin{axis}[width=5cm,scale only axis] + ... +\end{axis} +\end{tikzpicture} +\end{codeexample} + + \item Please note that up to the writing of this manual, \PGFPlots\ only estimates the size needed for axis- and tick labels. It does not include legends which have been placed outside of the axis\footnote{I.e. the `\texttt{width}' option will not work as expected, but the bounding box is still ok.}. This may be fixed in future versions. + + Use the |x=|\marg{dimension}, |y=|\marg{dimension} and |scale only axis| options if the scaling happens to be wrong. +\end{itemize} +\end{pgfplotskey} + +\begin{pgfplotskey}{height=\marg{dimen}} + See |width|. +\end{pgfplotskey} + +\begin{pgfplotskey}{scale only axis=\mchoice{true,false} (initially false)} +If |scale only axis| is enabled, label, tick and legend dimensions won't influence the size of the axis rectangle, that means |width| and |height| apply only to the axis rectangle + +If |scale only axis=false| (the default), \PGFPlots\ will try to produce the desired width \emph{including} labels, titles and ticks. +\end{pgfplotskey} + +\begin{pgfplotsxykeylist}{ + \x=\marg{dimen}, + \x={\{(\meta{x},\meta{y})\}}} +Sets the unit vectors for $x$ (or $y$). Every logical plot coordinate $(x,y)$ is drawn at the position +\[ x \cdot \begin{bmatrix} e_{xx} \\ e_{xy} \end{bmatrix} + y \cdot \begin{bmatrix} e_{yx} \\ e_{yy} \end{bmatrix}. \] +The unit vectors $e_x$ and $e_y$ determine the paper position in the current (always two dimensional) image. + +The key |x=|\marg{dimen} simply sets $e_x = (\meta{dimen},0)^T $ while |y=|\marg{dimen} sets $e_y = (0,\meta{dimen})^T$. +Here, \marg{dimen} is any \TeX\ size like |1mm|, |2cm| or |5pt|. It is allowed to specify a negative \marg{dimen}. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[x=1cm,y=1cm] +\addplot expression[domain=0:3] {2*x}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[x=1cm,y=-0.5cm] +\addplot expression[domain=0:3] {2*x}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})^T$ explicitly\footnote{Please note that you need extra curly braces around the vector. Otherwise, the comma will be interpreted as separator for the next key-value pair.}; the corresponding |y| key works similiarly. This allows to define skewed or rotated axes. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[x={(1cm,0.1cm)},y=1cm] +\addplot expression[domain=0:3] {2*x}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + x={(5pt,1pt)}, + y={(-4pt,4pt)}] +\addplot {1-x^2}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + Setting $x$ explicitly overrides the |width| option. Setting $y$ explicitly overrides the |height| option. + + Setting |x| and/or |y| for logarithmic axis will set the dimension used for $1 \cdot e \approx 2.71828$. + + Please note that it is \emph{not} possible to specify |x| as argument to |tikzpicture|. The option +\begin{codeexample}[code only] +\begin{tikzpicture}[x=1.5cm] +\begin{axis} + ... +\end{axis} +\end{tikzpicture} +\end{codeexample} + won't have any effect because an axis rescales its coordinates (see the |width| option). + +\paragraph{Limitations:} Unfortunately, skewed axes are \textbf{not available for bar plots}. +\index{Errors!Skewed axes and bar plots}% +\index{Bar Plots!Skewed axes problems}% +Furthermore, support for custom vectors in 3D plots is currently \textbf{experimental} and may not work at all, sorry. +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykey}{\x mode=\mchoice{normal,linear,log} (initially normal)} + Allows to choose between linear (=normal) or logarithmic axis scaling or logplots for each $x,y,z$-combination. + + Logarithmic plots use the current setting of |log basis x| and its variants to determine the basis (default is $e$). + % FIXME : replicated in pgfplots.reference.specifyrange.tex +\end{pgfplotsxykey} + +{\def\pgfmanualpdflabel#1#2{} +\begin{pgfplotsxykey}{\x\ dir=\mchoice{normal,reverse} (initially normal)} + Allows to revert axis directions such that values are given in decreasing order. + + This key is documented in all detail on page~\pageref{key:pgfplots:xydir}. +\end{pgfplotsxykey} +} + +\begin{pgfplotskey}{axis equal=\marg{true,false} (initially false)} + Each unit vector is set to the same length while the axis dimensions stay constant. Afterwards, the size ratios for each unit in $x$ and $y$ will be the same. + + Axis limits will be enlarge to compensate for the scaling effect. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[axis equal=false,grid=major] + \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; + \end{axis} +\end{tikzpicture} +\hspace{1cm} +\begin{tikzpicture} + \begin{axis}[axis equal=true,grid=major] + \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[axis equal=false,grid=major] + \addplot expression[domain=1:10000] {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\hspace{1cm} +\begin{tikzpicture} + \begin{loglogaxis}[axis equal=true,grid=major] + \addplot expression[domain=1:10000] {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + +\begin{pgfplotskey}{axis equal image=\marg{true,false} (initially false)} + Similar to |axis equal|, but the axis limits will stay constant as well (leading to smaller images). +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[axis equal image=false,grid=major] + \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; + \end{axis} +\end{tikzpicture} +\hspace{1cm} +\begin{tikzpicture} + \begin{axis}[axis equal image=true,grid=major] + \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[axis equal image=false,grid=major] + \addplot expression[domain=1:10000] {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\hspace{1cm} +\begin{tikzpicture} + \begin{loglogaxis}[axis equal image=true,grid=major] + \addplot expression[domain=1:10000] {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex new file mode 100644 index 00000000000..5ad417ecedc --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex @@ -0,0 +1,171 @@ + + +\subsection{Specifying the Plotted Range} + +\begin{pgfplotsxykeylist}{\x min=\marg{coord},\x max=\marg{coord}} +The options |xmin|, |xmax| and |ymin|, |ymax| allow to define the axis limits, i.e.\ the lower left and the upper right corner. Everything outside of the axis limits will be clipped away. + +Each missing limit will be determined automatically. + +If $x$-limits have been specified explicitly and $y$-limits are computed automatically, the automatic computation of $y$-limits will only considers points which fall into the specified $x$-range (and vice--versa). The same holds true if, for example, only |xmin| has been provided explicitly: in that case, |xmax| will be updated only for points for which $x \ge $|xmin| holds. This feature can be disabled using |clip limits=false|. + +Axis limits can be increased automatically using the |enlargelimits| option. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[xmin=0] + \addplot {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ymax=10] + \addplot {x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykey}{\x mode=\mchoice{normal,linear,log} (initially normal)} + Allows to choose between linear (=normal) or logarithmic axis scaling or logplots for each $x,y,z$-combination. + + Logarithmic plots use the current setting of |log basis x| and its variants to determine the basis (default is $e$). + % FIXME : replicated in pgfplots.reference.scaling.tex +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{\x\ dir=\mchoice{normal,reverse} (initially normal)} +\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/,}{}} + Allows to revert axis directions such that values are given in decreasing order. +\label{key:pgfplots:xydir} +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xlabel=$x$ \emph{decreasing} $\to$, + x dir=reverse] + \addplot {x+rand*0.3}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + ylabel=$y$ \emph{decreasing} $\to$, + y dir=reverse] + \addplot {x^2}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + Note, that axis descriptions and relative positioning macros will stay at the same place as they would for non--reversed axes. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + ylabel=$y$ \emph{decreasing} $\to$, + xlabel=$x$ normal, + title=reversed axis, + y dir=reverse, + colorbar, + colorbar style={y dir=reverse}] + \addplot+[mesh,scatter] {x^15}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + Note that |colorbar|s won't be reversed automatically, you will have to reverse the sequence of color bars manually in case this is required as in the preceding example. +\end{pgfplotsxykey} + +\begin{pgfplotskey}{clip limits=\mchoice{true,false} (initially true)} + Configures what to do if some, but not all axis limits have been specified explicitly. In case |clip limits=true|, the automatic limit computation will \emph{only} consider points which do not contradict the explicitly set limits. + + This option has nothing to do with path clipping, it only affects how the axis limits are computed. +\end{pgfplotskey} + +\begin{pgfplotsxykeylist}{enlarge \x\ limits=\mchoice{auto,true,false,upper,lower,\meta{val},value=\meta{val},abs value=\meta{val},\\ abs=\meta{val},rel=\meta{val}} (initially auto), + enlargelimits=\meta{common value}} +Enlarges the axis size for one axis (or all of them for |enlargelimits|) somewhat if enabled. + +You can set |xmin|, |xmax| and |ymin|, |ymax| to the minimum/maximum values of your data and |enlarge x limits| will enlarge the canvas such that the axis doesn't touch the plots. + +\begin{itemize} + \item The value \declaretext{true} enlarges the lower and upper limit. + \item The value \declaretext{false} uses tight axis limits as specified by the user (or read from input coordinates). + \item The value \declaretext{auto} will enlarge limits only for axis for which axis limits have been determined automatically. + + For threedimensional figures, the \declaretext{auto} mechanism applies only for the $z$ axis. The $x$ and $y$ axis won't be enlarged. + \item The value \declaretext{upper} enlarges only the upper axis limit while \declaretext{lower} enlarges only the lower axis limit. + \item Values like `|enlarge x limits=0.1|' will enlarge lower and upper axis limit relatively (in this example, $10\%$ of the axis limits will be added on both sides). + \item It is also possible to change just the relative threshold using the \declaretext{value=}\marg{val} key. It can be combined with any of the other possible values. For example, + + |\pgfplotsset{enlarge x limits={value=0.2,upper}}| + + will enlarge (only) the upper axis limit by $20\%$ of the axis range. Another example is + + |\pgfplotsset{enlarge x limits={value=0.2,auto}}| + + which changes the default threshold of the \declaretext{auto} value to $20\%$. + \item While |value| uses relative thresholds, \declaretext{abs value} is used in the same way with absolute values. + + \paragraph{Attention:} |abs value| is applied \emph{multiplicative} for logarithmic axes! That means |abs value=10| for a logarithmic axis adds $\log 10$ to upper and/or lower axis limits. + + \item Finally, \declaretext{abs=}\marg{value} is the same as |true,abs value=|\marg{value} and \declaretext{rel=}\marg{value} is the same as |true,value=|\marg{value}. +\end{itemize} +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot {5 * x^3 - x^2 + 4*x -2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[enlarge x limits=0.2] + \addplot {5 * x^3 - x^2 + 4*x -2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[minor x tick num=4, + enlarge x limits={rel=0.5,upper} + ] + \addplot {5 * x^3 - x^2 + 4*x -2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[minor x tick num=4, + enlarge x limits={abs=3} + ] + \addplot {5 * x^3 - x^2 + 4*x -2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[enlarge x limits={abs=11}] + \addplot+[domain=1:100000] {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + +\end{pgfplotsxykeylist} + +\begin{environment}{{pgfplotsinterruptdatabb}} +\index{Bounding Box Control!Disable \protect\emph{data} bounding box modifications} + Everything in \marg{environment contents} will not contribute to the data bounding box. +\end{environment} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.styleoptions.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.styleoptions.tex new file mode 100644 index 00000000000..3b37dc32c47 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.styleoptions.tex @@ -0,0 +1,299 @@ + +\subsection{Style Options} +\label{sec:styles} +\subsubsection{All Supported Styles} +\PGFPlots\ provides many styles to customize its appearance and behavior. They can be defined and changed in any place where keys are allowed. Furthermore, own styles are defined easily. + +\begin{handler}{{.style}=\marg{key-value-list}} + Defines or redefines a style \meta{key}. A style is a normal key which will set all options in \marg{key-value-list} when it is set. + + Use |\pgfplotsset{|\meta{key}|/.style={|\meta{key-value-list}|}}| to (re-) define a style \meta{key} in the namespace |/pgfplots|. +\end{handler} + +\begin{handler}{{.append style}=\marg{key-value-list}} + Appends \marg{key-value-list} to an already existing style \meta{key}. This is the preferred method to change the predefined styles: if you only append, you maintain compatibility with future versions. + + Use |\pgfplotsset{|\meta{key}|/.append style={|\meta{key-value-list}|}}| to append \marg{key-value-list} to the style \meta{key}. This will assume the prefix |/pgfplots|. +\end{handler} + +\subsubsection*{Styles installed for linear/logarithmic axis} + +\begin{stylekey}{/pgfplots/every axis (initially empty)} + Installed at the beginning of every axis. \Tikz\ options inside of it will be used for anything inside of the axis rectangle and any axis descriptions. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every semilogx axis (initially empty)} + Installed at the beginning of every plot with linear $x$~axis and logarithmic $y$~axis, but after `|every axis|'. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every semilogy axis (initially empty)} + Likewise, but with interchanged roles for $x$~and~$y$. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every loglog axis (initially empty)} + Installed at the beginning of every double--logarithmic plot. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every linear axis (initially empty)} + Installed at the beginning of every plot with normal axis scaling. +\end{stylekey} + +\subsubsection*{Styles installed for single plots} + +\begin{stylekey}{/pgfplots/every axis plot (initially empty)} + Installed for each plot. This style may contain options like samples, gnuplot parameters, error bars and it may contain options which affect the final drawing commands. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every axis plot post (initially empty)} + This style is similar to |every axis plot| in that is applies to any drawing command in |\addplot|. However, it is set \emph{after} any user defined styles or |cycle list| options. +\begin{codeexample}[] +\begin{tikzpicture} +\pgfplotsset{ + every axis plot post/.append style= + {mark=none}} + +\begin{axis}[ + legend style={ + at={(0.03,0.97)},anchor=north west}, + domain=0:1] + \addplot {x^2}; + \addplot {exp(x)}; + \legend{$x^2$,$e^x$} +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{stylekey} + +\begin{stylekey}{/pgfplots/every axis plot no \# (initially empty)} + Used for every \#th plot where $\#=0,1,2,3,4,\dotsc$. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every forget plot (initially empty)} + Used for every plot which has |forget plot| activated. +\end{stylekey} + +\pgfplotsshortstylekey forget plot style=every forget plot\pgfeov + +\subsubsection*{Styles for axis descriptions} + +\begin{stylekey}{/pgfplots/every axis label (initially empty)} + Used for all axis label (like |xlabel| and |ylabel|). +\end{stylekey} + +\pgfplotsshortstylekey label style=every axis label\pgfeov + +\begin{xystylekey}{/pgfplots/every axis \x\ label} + Used only~$x$ or only for~$y$ labels, installed after `|every axis label|'. + + The initial settings are set by |xlabel absolute| and its variants (if the initial configuration |compat=pre 1.3| is active) or |xlabel near ticks| which provides the better spacing as it incorporates the tick label sizes to compute the position. + +\paragraph{Attention:} These styles will be overwritten by |axis x line| and/or |axis y line|. Please remember to place your modifications after the axis line variations. +\end{xystylekey} + +\pgfplotsshortxystylekeys \x\ label style,\x label style=every axis \x\ label\pgfeov + +\begin{stylekey}{/pgfplots/every axis title} + Used for any axis title. The |at=|\parg{x,y} syntax will place the title using |axis description cs|. + +The initial setting is +\begin{codeexample}[code only] +\pgfplotsset{every axis title/.style={at={(0.5,1)},above,yshift=6pt}} +\end{codeexample} +\end{stylekey} + +\pgfplotsshortstylekey title style=every axis title\pgfeov + +\begin{stylekey}{/pgfplots/every axis legend} + Installed for each legend. As described for |axis description cs|, the legend's position can be placed using coordinates between $0$~and~$1$ (it employs |axis description cs| automatically). + + The initial setting is +\begin{codeexample}[code only] +\pgfplotsset{every axis legend/.style={ + cells={anchor=center}, + inner xsep=3pt,inner ysep=2pt,nodes={inner sep=2pt,text depth=0.15em}, + anchor=north east, + shape=rectangle, + fill=white,draw=black, + at={(0.98,0.98)}}} +\end{codeexample} +\end{stylekey} + +\pgfplotsshortstylekey legend style=every axis legend\pgfeov + +\subsubsection*{Styles for axis lines} +\begin{xystylekey}{/pgfplots/every outer \x\ axis line (initially empty)} + Installed for every axis line which lies on the outer box. + + If you want arrow heads, you may also need to check the |separate axis lines| boolean key. +\end{xystylekey} + +\begin{xystylekey}{/pgfplots/every inner \x\ axis line (initially empty)} + Installed for every axis line which is drawn using the |center| or |middle| options. +\end{xystylekey} + +\begin{pgfplotsxykeylist}{% + axis line style=\marg{key-value-list}, + inner axis line style=\marg{key-value-list}, + outer axis line style=\marg{key-value-list}, + \x\ axis line style=\marg{key-value-list}} + These options modify selects parts of the axis line styles. They set |every inner x axis line| and |every outer x axis line| and the respective $y$ variants. +\end{pgfplotsxykeylist} + +\noindent +Please refer to section~\ref{pgfplots:page:axislines} on page~\pageref{pgfplots:page:axislines} for details about styles for axis lines. + +\begin{stylekey}{/pgfplots/every 3d box foreground} + Installed for the parts drawn by |3d box=complete|. This affects axis lines, tick lines and grid lines drawn in the \emph{foreground}. The background drawing operations have already been done when this style is evaluated. +\end{stylekey} + +\pgfplotsshortstylekey 3d box foreground style=every 3d box foreground\pgfeov + + +\subsubsection*{Styles for ticks} + +\begin{stylekey}{/pgfplots/every tick (initially very thin,gray)} + Installed for each of the small tick \emph{lines}. +\end{stylekey} + +\pgfplotsshortstylekey tick style=every tick\pgfeov + +\begin{stylekey}{/pgfplots/every minor tick (initially empty)} + Used for each minor tick line, installed after `|every tick|'. +\end{stylekey} + +\pgfplotsshortstylekey minor tick style=every minor tick\pgfeov + +\begin{stylekey}{/pgfplots/every major tick (initially empty)} + Used for each major tick line, installed after `|every tick|'. +\end{stylekey} + +\pgfplotsshortstylekey major tick style=every major tick\pgfeov + +\begin{stylekey}{/pgfplots/every tick label (initially empty)} + Used for each $x$~and~$y$ tick labels. +\end{stylekey} + +\pgfplotsshortxystylekeys tick label style,ticklabel style=every tick label\pgfeov + +\begin{xystylekey}{/pgfplots/every \x\ tick label (initially empty)} + Used for each $x$ (or $y$, respectively) tick label, installed after `|every tick label|'. +\end{xystylekey} + +\pgfplotsshortxystylekeys \x\ tick label style,\x ticklabel style=every \x\ tick label\pgfeov + +\begin{xystylekey}{/pgfplots/every \x\ tick scale label} + Configures placement and display of the nodes containing the order of magnitude of tick labels, see section~\ref{sec:scaled:ticks} for more information about |scaled ticks|. + +The initial settings are +\begin{codeexample}[code only] +\pgfplotsset{ + every x tick scale label/.style={at={(1,0)},yshift=-2em,left,inner sep=0pt}, + every y tick scale label/.style={at={(0,1)},above right,inner sep=0pt,yshift=0.3em}} +\end{codeexample} +\end{xystylekey} + +\pgfplotsshortxystylekey \x\ tick scale label style=every \x\ tick scale label\pgfeov + +\begin{xystylekey}{/pgfplots/every \x\ tick (initially empty)} + Installed for tick \emph{lines} on either $x$ or $y$ axis. +\end{xystylekey} + +\pgfplotsshortxystylekey \x\ tick style=every \x\ tick\pgfeov + +\begin{xystylekey}{/pgfplots/every minor \x\ tick (initially empty)} + Installed for minor tick lines on either $x$ or $y$ axis. +\end{xystylekey} + +\pgfplotsshortxystylekey minor \x\ tick style=every minor \x\ tick\pgfeov + +\begin{xystylekey}{/pgfplots/every major \x\ tick (initially empty)} + Installed for major tick lines on either $x$ or $y$ axis. +\end{xystylekey} +\pgfplotsshortxystylekey major \x\ tick style=every major \x\ tick\pgfeov + +\begin{xystylekey}{/pgfplots/every extra \x\ tick} + Allows to configure the appearance of `|extra x ticks|'. This style is installed before touching the first extra $x$~tick. It is possible to set any option which affects tick or grid line generation. + +The initial setting is +\begin{codeexample}[code only] +\pgfplotsset{ + every extra x tick/.style={/pgfplots/log identify minor tick positions=true}, + every extra y tick/.style={/pgfplots/log identify minor tick positions=true}} +\end{codeexample} + + Useful examples are shown below. +\begin{codeexample}[code only] +\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}} +\end{codeexample} +\end{xystylekey} + +\pgfplotsshortxystylekey extra \x\ tick style=every extra \x\ tick\pgfeov + +\begin{stylekey}{/pgfplots/extra tick style=\marg{key-value-list}} + An abbreviation which appends \meta{key-value-list} to |every extra x tick|, |every extra y tick| and |every extra z tick|. +\end{stylekey} + + + +\subsubsection*{Styles for grid lines} + +\begin{stylekey}{/pgfplots/every axis grid (initially thin,black!25)} + Used for each grid line. +\end{stylekey} + +\pgfplotsshortstylekey grid style=every axis grid\pgfeov + +\begin{stylekey}{/pgfplots/every minor grid (initially empty)} + Used for each minor grid line, installed after `|every axis grid|'. +\end{stylekey} + +\pgfplotsshortstylekey minor grid style=every minor grid\pgfeov + +\begin{stylekey}{/pgfplots/every major grid (initially empty)} + Likewise, for major grid lines. +\end{stylekey} + +\pgfplotsshortstylekey major grid style=every major grid\pgfeov + +\begin{xystylekey}{/pgfplots/every axis \x\ grid (initially empty)} + Used for each grid line in either $x$ or $y$ direction. +\end{xystylekey} + +\pgfplotsshortxystylekey \x\ grid style=every axis \x\ grid\pgfeov + +\begin{xystylekey}{/pgfplots/every minor \x\ grid (initially empty)} + Used for each minor grid line in either $x$ or $y$ direction. +\end{xystylekey} + +\pgfplotsshortxystylekey minor \x\ grid style=every minor \x\ grid\pgfeov + +\begin{xystylekey}{/pgfplots/every major \x\ grid (initially empty)} + Used for each major grid line in either $x$ or $y$ direction. +\end{xystylekey} + +\pgfplotsshortxystylekey major \x\ grid style=every major \x\ grid\pgfeov + +\subsubsection*{Styles for error bars} + +\begin{stylekey}{/pgfplots/every error bar (initially thin)} + Installed for every error bar. +\end{stylekey} + +\pgfplotsshortstylekey error bars/error bar style=every error bar\pgfeov + +\subsubsection{(Re-)Defining Own Styles} +\label{sec:styles:own}% +Use |\pgfplotsset{|\meta{style name}|/.style=|\marg{key-value-list}|}| +to create own styles. If \meta{style name} exists already, it will be replaced. Please note that it is \emph{not} possible to use the \Tikz-command |\tikzstyle|\marg{style name}|=[]| in this context\footnote{This was possible in a previous version and is still supported for backwards compatibility. But in some cases, it may not work as expected.}. +\begin{codeexample}[] +\pgfplotsset{my personal style/.style= + {grid=major,font=\large}} + +\begin{tikzpicture} +\begin{axis}[my personal style] + \addplot coordinates {(0,0) (1,1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic-transformations.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic-transformations.tex new file mode 100644 index 00000000000..1b6bcb55191 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic-transformations.tex @@ -0,0 +1,169 @@ + + +\subsection{Symbolic Coordinates and User Transformations} +\label{pgfplots:sec:symbolic:coords} +\PGFPlots\ supports user transformations which can be applied to input and output coordinates. Suppose the plot shall display days versus account statements over time. Then, one wants to visualize date versus credit balance. But: dates need to be transformed to numbers before doing so! Furthermore, tick labels shall be displayed as dates as well. This, and more general transformations, can be realized using the |x coord trafo| and |y coord trafo| keys. + +\paragraph{Remark:} This section applies to users who want to have non-standard input \emph{coordinates}. If you have normal numbers which don't need to be transformed and you like to have special symbols as tick labels, you should consider using the |xticklabels| (|yticklabels|) key described on page~\pageref{pgfplots:key:xticklabels}. + +\begin{pgfplotsxycodekeylist}{ + \x\ coord trafo, + \x\ coord inv trafo} + These code keys allow arbitrary coordinate transformations which are applied to input coordinates and output tick labels. + + The |x coord trafo| and |y coord trafo| command keys take one argument which is the input coordinate. They are expected to set |\pgfmathresult| to the final value. + + At this level, the input coordinate is provided as it is found in the |\addplot| statement. For example, if $x$ coordinates are actually of the form \meta{year}-\meta{month}-\meta{day}, for example |2008-01-05|, then a useful coordinate transformation would transform this string into a number (see below for a predefined realization). + + In short, \emph{no} numerics has been applied to input coordinates when this transformation is applied\footnote{Of course, if coordinates have been generated by gnuplot or \pgfname, this does no longer hold.}. + + The input coordinate transformation is applied to + \begin{itemize} + \item any input coordinates (specified with |\addplot| or |axis cs|), + \item any user-specified |xtick| or |ytick| options, + \item any user-specified |extra x ticks| and |extra y ticks| options, + \item any user-specified axis limits like |xmin| and |xmax|. + \end{itemize} + + The output coordinate transformation |x coord inv trafo| is applied to tick positions just before evaluating the |xticklabel| and |yticklabel| keys. The argument to |x coord inv trafo| is a fixed point number (which may have trailing zeros after the period). + The tick label code may use additional macros defined by the inverse transformation. + + Remark: \PGFPlots\ will continue to produce tick positions as usual, no extra magic is applied. It may be necessary to provide tick positions explicitly if the default doesn't respect the coordinate space properly. + + The initial value of these keys is +\begin{codeexample}[code only] +\pgfplotsset{ + x coord trafo/.code={}, + x coord inv trafo/.code={}} +\end{codeexample} + \noindent which simply disables the transformation (the same for $y$, of course). + + \paragraph{Remark:} It might be necessary to set +\begin{codeexample}[code only] +\pgfplotsset{ + xticklabel={\tick}, + scaled x ticks=false, + plot coordinates/math parser=false, +} +\end{codeexample} + \noindent in order to avoid number formatting routines on |\tick| or numerics for tick scale methods. This is done automatically by the predefined symbolic coordinate styles (see below). +\end{pgfplotsxycodekeylist} + +\subsubsection{String Symbols as Input Coordinates} +It is possible to provide a string dictionary to \PGFPlots. An input coordinate can then use any symbol provided in that dictionary. +\begin{pgfplotsxykeylist}{symbolic \x\space coords=\marg{dictionary}}% + A styles which sets |x coord trafo| and |x coord inv trafo| (or the respective |y| or |z| variants) such that any element in \marg{dictionary} is a valid input coordinate. The \marg{dictionary} can be a comma separated list or a list terminated with `|\\|'. In both case, white spaces are considered to be part of the names (use `|%|' at end of lines). + + The dictionary will assign integer numbers to every element. These integers are used internally for arithmetics. Finally, the inverse transformation takes a fixed point number and maps it to the nearest integer, and that integer is mapped into the dictionary. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[symbolic x coords={a,b,c,d,e,f,g,h,i}] + \addplot+[smooth] coordinates { + (a,42) + (b,50) + (c,80) + (f,60) + (g,62) + (i,90)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + The effect of the transformation is simply that input coordinates can be elements of the dictionary and tick labels will be chosen out of this dictionary as well. +\end{pgfplotsxykeylist} + +\subsubsection{Dates as Input Coordinates} +\label{pgfplots:sec:date:coords} +The already mentioned application of using dates as input coordinates has been predefined, together with support for hours and minutes. It relies on the \pgfname\ calendar library which converts dates to numbers in the julian calendar. Then, one coordinate unit is one day. + +\begin{pgfplotslibrary}{dateplot} + Loads the coordinate transformation code. +\end{pgfplotslibrary} + +\begin{stylekey}{/pgfplots/date coordinates in=\mchoice{x,y}} + Installs |x coord trafo| and |x coord inv trafo| (or the respective $y$ variant) such that ISO dates of the form \meta{year}|-|\meta{month}|-|\meta{day} are accepted. For example, |2006-02-28| will be converted to an ``appropriate'' integer using the julian calender. Input coordinates may be of the form + + \meta{year}|-|\meta{month}|-|\meta{day} + + \noindent or they may contain times as + + \meta{year}|-|\meta{month}|-|\meta{day} \meta{hour}|:|\meta{minute}. + + The result of the transformation are numbers where one unit is one day and times are fractional numbers. + + The transformation is realized using the \pgfname-calendar module, see \cite[Calendar Library]{tikz}. This reference also contains more information about extended syntax options for dates. + + The inverse transformation provides the following macros which are available during tick label evaluation (i.e. when used inside of |xticklabel| or |yticklabel|): + \begin{itemize} + \item \declareandlabel{\year} expands to the year component, + \item \declareandlabel{\month} expands to the month component, + \item \declareandlabel{\day} expands to the day component, + \item \declareandlabel{\hour} expands to the hour component (using two digits), + \item \declareandlabel{\Hour} expands to the hour component (but omits leading zeros), + \item \declareandlabel{\minute} expands to the minute component (two digits), + \item \declareandlabel{\Minute} expands to the minute component (omits leadings zeros), + \item \declareandlabel{\lowlevel} expands to the low level number representing the tick, + \item \declareandlabel{\second} will always be |00|. + \end{itemize} + This allows to use |\day.\month.\year| or |\day. \hour:\minute| inside of |xticklabel|, for example. + + A complete example (with fictional data) is shown below. +\pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}} +% \usepgfplotslibrary{dateplot}\usepackage{eurosym} +\begin{codeexample}[] +% requires \usepgfplotslibrary{dateplot} ! + +\pgfplotstabletypeset[string type]{plotdata/accounts.dat} + +\begin{tikzpicture} + \begin{axis}[ + date coordinates in=x, + xticklabel={\day.\month.}, + xlabel={2008}, + stack plots=y, + yticklabel={\pgfmathprintnumber{\tick}\EUR{}}, % <- requires \usepackage{eurosym} + ylabel=Total credit, + ylabel style={yshift=10pt}, + legend style={ + at={(0.5,-0.3)},anchor=north,legend columns=-1}] + + \addplot table[x=date,y=account1] {plotdata/accounts.dat}; + \addplot table[x=date,y=account2] {plotdata/accounts.dat}; + \addplot table[x=date,y=account3] {plotdata/accounts.dat}; + \legend{Giro,Tagesgeld,Sparbuch} + \end{axis} +\end{tikzpicture} +\end{codeexample} + +% \usepgfplotslibrary{dateplot}\usepackage{eurosym} +\begin{codeexample}[] +% requires \usepgfplotslibrary{dateplot} ! +\begin{tikzpicture} + \begin{axis}[ + date coordinates in=x, + xtick=data, + xticklabel style= + {rotate=90,anchor=near xticklabel}, + xticklabel=\day. \hour:\minute, + date ZERO=2009-08-18,% <- improves precision! + ] + \addplot coordinates { + (2009-08-18 09:00, 050) + (2009-08-18 12:00, 100) + (2009-08-18 15:00, 100) + (2009-08-18 18:35, 100) + (2009-08-18 21:30, 040) + (2009-08-19, 020) + (2009-08-19 3:00, 000) + (2009-08-19 6:0, 035) + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\paragraph{Attention:} If you intend to use hours and minutes, you should \emph{always} provide the |date ZERO| to maintain adequate precision! +\end{stylekey} + +\begin{pgfplotskey}{date ZERO=\meta{year}-\meta{month}-\meta{day} (initially 2006-01-01)} + A technical key which defines the $0$ coordinate of |date coordinates in|. Users will never see the resulting numbers, so one probably never needs to change it. However, the resulting numbers may become very large and a mantisse of 6 significant digits may not be enough to get accurate results. In this case, |date ZERO| should be set to a number which falls into the input date range. +\end{pgfplotskey} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic.tex new file mode 100644 index 00000000000..1bc68bb6dfa --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.symbolic.tex @@ -0,0 +1,168 @@ + + +\subsection{Symbolic Coordinates and User Transformations} +\label{pgfplots:sec:symbolic:coords} +\PGFPlots\ supports user transformations which can be applied to input and output coordinates. Suppose the plot shall display days versus account statements over time. Then, one wants to visualize date versus credit balance. But: dates need to be transformed to numbers before doing so! Furthermore, tick labels shall be displayed as dates as well. This, and more general transformations, can be realized using the |x coord trafo| and |y coord trafo| keys. + +\paragraph{Remark:} This section applies to users who want to have non-standard input \emph{coordinates}. If you have normal numbers which don't need to be transformed and you like to have special symbols as tick labels, you should consider using the \declaretext{[xyz]ticklabels} key described on page~\pageref{pgfplots:key:xticklabels}. + +\begin{pgfplotsxycodekeylist}{ + \x\ coord trafo, + \x\ coord inv trafo} + These code keys allow arbitrary coordinate transformations which are applied to input coordinates and output tick labels. + + The |x coord trafo| and |y coord trafo| command keys take one argument which is the input coordinate. They are expected to set |\pgfmathresult| to the final value. + + At this level, the input coordinate is provided as it is found in the |\addplot| statement. For example, if $x$ coordinates are actually of the form \meta{year}-\meta{month}-\meta{day}, for example |2008-01-05|, then a useful coordinate transformation would transform this string into a number (see below for a predefined realization). + + In short, \emph{no} numerics has been applied to input coordinates when this transformation is applied\footnote{Of course, if coordinates have been generated by gnuplot or \pgfname, this does no longer hold.}. + + The input coordinate transformation is applied to + \begin{itemize} + \item any input coordinates (specified with |\addplot| or |axis cs|), + \item any user-specified |xtick| or |ytick| options, + \item any user-specified |extra x ticks| and |extra y ticks| options, + \item any user-specified axis limits like |xmin| and |xmax|. + \end{itemize} + + The output coordinate transformation |x coord inv trafo| is applied to tick positions just before evaluating the |xticklabel| and |yticklabel| keys. The argument to |x coord inv trafo| is a fixed point number (which may have trailing zeros after the period). + The tick label code may use additional macros defined by the inverse transformation. + + Remark: \PGFPlots\ will continue to produce tick positions as usual, no extra magic is applied. It may be necessary to provide tick positions explicitly if the default doesn't respect the coordinate space properly. + + The initial value of these keys is +\begin{codeexample}[code only] +\pgfplotsset{ + x coord trafo/.code={}, + x coord inv trafo/.code={}} +\end{codeexample} + \noindent which simply disables the transformation (the same for $y$, of course). + + \paragraph{Remark:} It might be necessary to set +\begin{codeexample}[code only] +\pgfplotsset{ + /pgfplots/xticklabel={\tick}, + /pgfplots/scaled x ticks=false +} +\end{codeexample} + \noindent in order to avoid number formatting routines on |\tick| or numerics for tick scale methods. This is done automatically by the predefined symbolic coordinate styles (see below). +\end{pgfplotsxycodekeylist} + +\subsubsection{String Symbols as Input Coordinates} +It is possible to provide a string dictionary to \PGFPlots. An input coordinate can then use any symbol provided in that dictionary. +\begin{pgfplotsxykeylist}{symbolic \x\space coords=\marg{dictionary}}% + A styles which sets |x coord trafo| and |x coord inv trafo| (or the respective |y| or |z| variants) such that any element in \marg{dictionary} is a valid input coordinate. The \marg{dictionary} can be a comma separated list or a list terminated with `|\\|'. In both case, white spaces are considered to be part of the names (use `|%|' at end of lines). + + The dictionary will assign integer numbers to every element. These integers are used internally for arithmetics. Finally, the inverse transformation takes a fixed point number and maps it to the nearest integer, and that integer is mapped into the dictionary. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[symbolic x coords={a,b,c,d,e,f,g,h,i}] + \addplot+[smooth] coordinates { + (a,42) + (b,50) + (c,80) + (f,60) + (g,62) + (i,90)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + The effect of the transformation is simply that input coordinates can be elements of the dictionary and tick labels will be chosen out of this dictionary as well. +\end{pgfplotsxykeylist} + +\subsubsection{Dates as Input Coordinates} +\label{pgfplots:sec:date:coords} +The already mentioned application of using dates as input coordinates has been predefined, together with support for hours and minutes. It relies on the \pgfname\ calendar library which converts dates to numbers in the julian calendar. Then, one coordinate unit is one day. + +\begin{pgfplotslibrary}{dateplot} + Loads the coordinate transformation code. +\end{pgfplotslibrary} + +\begin{stylekey}{/pgfplots/date coordinates in=\mchoice{x,y}} + Installs |x coord trafo| and |x coord inv trafo| (or the respective $y$ variant) such that ISO dates of the form \meta{year}|-|\meta{month}|-|\meta{day} are accepted. For example, |2006-02-28| will be converted to an ``appropriate'' integer using the julian calender. Input coordinates may be of the form + + \meta{year}|-|\meta{month}|-|\meta{day} + + \noindent or they may contain times as + + \meta{year}|-|\meta{month}|-|\meta{day} \meta{hour}|:|\meta{minute}. + + The result of the transformation are numbers where one unit is one day and times are fractional numbers. + + The transformation is realized using the \pgfname-calendar module, see \cite[Calendar Library]{tikz}. This reference also contains more information about extended syntax options for dates. + + The inverse transformation provides the following macros which are available during tick label evaluation (i.e. when used inside of |xticklabel| or |yticklabel|): + \begin{itemize} + \item |\year| expands to the year component, + \item |\month| expands to the month component, + \item |\day| expands to the day component, + \item |\hour| expands to the hour component (using two digits), + \item |\Hour| expands to the hour component (but omits leading zeros), + \item |\minute| expands to the minute component (two digits), + \item |\Minute| expands to the minute component (omits leadings zeros), + \item |\lowlevel| expands to the low level number representing the tick, + \item |\second| will always be |00|. + \end{itemize} + This allows to use |\day.\month.\year| or |\day. \hour:\minute| inside of |xticklabel|, for example. + + A complete example (with fictional data) is shown below. +\pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}} +% \usepgfplotslibrary{dateplot}\usepackage{eurosym} +\begin{codeexample}[] +% requires \usepgfplotslibrary{dateplot} ! + +\pgfplotstabletypeset[string type]{plotdata/accounts.dat} + +\begin{tikzpicture} + \begin{axis}[ + date coordinates in=x, + xticklabel={\day.\month.}, + xlabel={2008}, + stack plots=y, + yticklabel={\pgfmathprintnumber{\tick}\EUR{}}, % <- requires \usepackage{eurosym} + ylabel=Total credit, + ylabel style={yshift=10pt}, + legend style={ + at={(0.5,-0.3)},anchor=north,legend columns=-1}] + + \addplot table[x=date,y=account1] {plotdata/accounts.dat}; + \addplot table[x=date,y=account2] {plotdata/accounts.dat}; + \addplot table[x=date,y=account3] {plotdata/accounts.dat}; + \legend{Giro,Tagesgeld,Sparbuch} + \end{axis} +\end{tikzpicture} +\end{codeexample} + +% \usepgfplotslibrary{dateplot}\usepackage{eurosym} +\begin{codeexample}[] +% requires \usepgfplotslibrary{dateplot} ! +\begin{tikzpicture} + \begin{axis}[ + date coordinates in=x, + xtick=data, + xticklabel style= + {rotate=90,anchor=near xticklabel}, + xticklabel=\day. \hour:\minute, + date ZERO=2009-08-18,% <- improves precision! + ] + \addplot coordinates { + (2009-08-18 09:00, 050) + (2009-08-18 12:00, 100) + (2009-08-18 15:00, 100) + (2009-08-18 18:35, 100) + (2009-08-18 21:30, 040) + (2009-08-19, 020) + (2009-08-19 3:00, 000) + (2009-08-19 6:0, 035) + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\paragraph{Attention:} If you intend to use hours and minutes, you should \emph{always} provide the |date ZERO| to maintain adequate precision! +\end{stylekey} + +\begin{pgfplotskey}{date ZERO=\meta{year}-\meta{month}-\meta{day} (initially 2006-01-01)} + A technical key which defines the $0$ coordinate of |date coordinates in|. Users will never see the resulting numbers, so one probably never needs to change it. However, the resulting numbers may become very large and a mantisse of 6 significant digits may not be enough to get accurate results. In this case, |date ZERO| should be set to a number which falls into the input date range. +\end{pgfplotskey} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex index af59f8e7109..b2a92e7868d 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex @@ -1,5555 +1,23 @@ % main=manual.tex -\section{Command Reference} -\subsection{The Axis-environments} -There is an axis environment for linear scaling, two for semi-logarithmic scaling and one for double-logarithmic scaling. -\begin{environment}{{axis}\oarg{options}} - The axis environment for normal plots with linear axis scaling. - - The `|every linear axis|' style key can be modified with -\begin{codeexample}[code only] -\pgfplotsset{every linear axis/.append style={...}} -\end{codeexample} -to install styles specifically for linear axes. These styles can contain both \Tikz- and \PGFPlots\ options. -\end{environment} - -\begin{environment}{{semilogxaxis}\oarg{options}} -The axis environment for logarithmic scaling of~$x$ and normal scaling of~$y$. -Use -\begin{codeexample}[code only] -\pgfplotsset{every semilogx axis/.append style={...}} -\end{codeexample} -to install styles specifically for the case with |xmode=log|, |ymode=normal|. -\end{environment} - -\begin{environment}{{semilogyaxis}\oarg{options}} -The axis environment for normal scaling of~$x$ and logarithmic scaling of~$y$, - -The style `|every semilogy axis|' will be installed for each such plot. -\end{environment} - -\begin{environment}{{loglogaxis}\oarg{options}} -The axis environment for logarithmic scaling of both, $x$~and~$y$ axes, -As for the other axis possibilities, there is a style `|every loglog axis|' which is installed at the environment's beginning. -\end{environment} - -\noindent -They are all equivalent to -\begin{codeexample}[code only] -\begin{axis}[ - xmode=log|normal, - ymode=log|normal] -... -\end{axis} -\end{codeexample} -\noindent -with properly set variables `|xmode|' and `|ymode|' (see below). - -\subsection{The Plot Command} -\label{sec:addplot}% -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ymin=0,ymax=1,enlargelimits=false] -\addplot - [blue!80!black,fill=blue,fill opacity=0.5] -coordinates -{(0,0.1) (0.1,0.15) (0.2,0.5) (0.3,0.62) - (0.4,0.56) (0.5,0.58) (0.6,0.65) (0.7,0.6) - (0.8,0.58) (0.9,0.55) (1,0.52)} -|- (axis cs:0,0) -- cycle; - -\addplot - [red,fill=red!90!black,opacity=0.5] -coordinates -{(0,0.25) (0.1,0.27) (0.2,0.24) (0.3,0.24) - (0.4,0.26) (0.5,0.3) (0.6,0.23) (0.7,0.2) - (0.8,0.15) (0.9,0.1) (1,0.1)} -|- (axis cs:0,0) -- cycle; - -\addplot[green!20!black] coordinates - {(0,0.4) (0.2,0.75) (1,0.75)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot plot - [id=parable,domain=-5:5] - gnuplot{4*x**2 - 5} - node[pin=180:{$4x^2-5$}]{}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{command}{\addplot\oarg{style options} \textcolor{gray}{plot\oarg{behavior options}} \meta{input data} \meta{trailing path commands};} -This is the main plotting command, available within each axis environment. - -It reads point coordinates from one of the available input sources specified by \meta{input data}, updates limits, remembers \meta{style options} for use in a legend (if any) and applies any necessary coordinate transformations (or logarithms). - -The \meta{style options} can be omitted in which case the next entry from the |cycle list| will be inserted as \meta{style options}. These keys characterize the plot's type like linear interpolation, smooth plot, constant interpolation or bar plot and define colors, markers and line specifications. - -The optional \meta{behavior options} can be used to modify plot variants, for example to add error bars. They are described when needed. - -The \meta{input data} is one of several coordinate input tools which are described in more detail below. Finally, if |\addplot| successfully processed all coordinates from \meta{input data}, it generates \Tikz-drawing commands (for example |plot coordinate {...}|). If \meta{trailing path commands} is not empty, these arguments are appended to the final drawing command. - -\noindent -Some more details: -\begin{itemize} - \item The style |/pgfplots/every axis plot| will be installed at the beginning of \meta{style options}. That means you can use -\begin{codeexample}[code only] -\pgfplotsset{every axis plot/.append style={...}} -\end{codeexample} - to add options to all your plots - maybe to set line widths to |thick|. Furthermore, if you have more than one plot inside of an axis, you can also use -\begin{codeexample}[code only] -\pgfplotsset{every axis plot no 3/.append style={...}} -\end{codeexample} - to modify options for the plot with number~$3$ only. The first plot has number~$0$. - \item The \meta{style options} are remembered for the legend. Furthermore, they are available as `|current plot style|' as long as the path is not yet finished or in associated error bars. - \item See subsection~\ref{sec:markers} for a list of available markers and line styles. - \item For log plots, \PGFPlots\ will compute the natural logarithm $\log(\cdot)$ numerically. This works with normal fixed point numbers or in scientific notation. For example, the following numbers are valid input to |\addplot|. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{loglogaxis} -\addplot coordinates { - (769, 1.6227e-04) - (1793, 4.4425e-05) - (4097, 1.2071e-05) - (9217, 3.2610e-06) - (2.2e5, 2.1E-6) - (1e6, 0.00003341) - (2.3e7, 0.00131415) -}; -\end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - You can represent arbitrarily small or very large numbers as long as its logarithm can be represented as a \TeX-length (up to about~$16384$). Of course, any coordinate~$x\le 0$ is not possible since the logarithm of a non-positive number is not defined. Such coordinates will be skipped automatically. - - \item For normal plots, \PGFPlots\ applies floating point arithmetics to support large or small numbers like 0.00000001234 or $1.234\cdot 10^{24}$. Its number range is much larger than \TeX's native support for numbers. The relative precision is at least~$5$ significant decimal digits for the mantisse. As soon as the axes limits are completely known, \PGFPlots\ applies a transformation which maps these floating point numbers into \TeX-precision using transformations - \[ T_x(x) = 10^{s_x} \cdot x - a_x \text{ and } T_y(y) = 10^{s_y} \cdot y - a_y \] - with properly chosen integers $s_x, s_y \in \Z$ and shifts $a_x,a_y\in \R$. Section~\ref{sec:disabledatascaling} contains a description of |disabledatascaling| and provides more details about the transformation. - \index{Accuracy!Floating Point in \PGFPlots}% - - \item As a consequence of the coordinate parsing routines, you can't use the mathematical expression parsing method of \PGF\ as coordinates (that means: you will need to provide coordinates without suffixes like ``cm'' or ``pt'' and you can't invoke mathematical functions). - - \item If you did not specify axis limits for $x$ and $y$ manually, |\addplot| will compute them automatically. - The automatic computation of axis limits works as follows: - \begin{enumerate} - \item Every coordinate will be checked. Care has been taken to avoid \TeX's limited numerical capabilities. - \item Since more than one |\addplot| command may be used inside of |\begin{axis}...\end{axis}|, all drawing commands will be postponed until |\end{axis}|. - \end{enumerate} -\end{itemize} -\end{command} - -\subsubsection{Coordinate Lists} -\label{pgfplots:providing:input} - -\begin{addplotoperation}[]{coordinates}{\marg{coordinate list}} -The `|plot coordinates|' command is provided by \Tikz\ and reads its input data from a sequence of point coordinates. -\begin{codeexample}[code only] -\addplot plot coordinates { - (0,0) - (0.5,1) - (1,2) -}; -\end{codeexample} - -You can also supply error coordinates (reliability bounds) if you are interested in error bars. Simply append the error coordinates with `|+- |\parg{ex,ey}' to the associated coordinate: -\begin{codeexample}[code only] -\addplot plot coordinates { - (0,0) +- (0.1,0) - (0.5,1) +- (0.4,0.2) - (1,2) - (2,5) +- (1,0.1) -}; -\end{codeexample} -or -\begin{codeexample}[code only] -\addplot plot coordinates { - (1300,1e-6) +- (0.1,0.2) - (2600,5e-7) +- (0.2,0.5) - (4000,1e-7) +- (0.1,0.01) -}; -\end{codeexample} -These error coordinates are only used in case of error bars, see section~\ref{sec:errorbars}. You will also need to configure whether these values denote absolute or relative errors. - -The coordinates as such can be numbers as |+5|, |-1.2345e3|, |35.0e2|, |0.00000123| or |1e2345e-8|. They are not limited to \TeX's precision. - -Furthermore, |plot coordinates| allows to define ``meta data'' for each coordinate. The interpretation of meta data depends on the visualization technique: for scatter plots, meta data can be used to define colors or style associations for every point (see page~\pageref{pgfplots:scatterclasses} for an example). Meta data (if any) must be provided after the coordinates and after error bar bounds (if any) in square brackets: -\begin{codeexample}[code only] -\addplot plot coordinates { - (1300,1e-6) [1] - (2600,5e-7) [2] - (4000,1e-7) [3] -}; -\end{codeexample} -Please refer to the documentation of |scatter src| on page~\pageref{pgfplots:scatter:src} for more information about per point meta data. -\end{addplotoperation} - -\subsubsection{Reading Coordinates From Files} - -\begin{addplotoperation}[]{file}{\marg{name}} -\PGFPlots\ supports two ways to read plot coordinates of external files, and one of them is the \Tikz-command `|plot file|'. It is to be used like -\begin{codeexample}[code only] -\addplot plot file {datafile.dat}; -\end{codeexample} -where \marg{name} is a text file with at least two columns which will be used as $x$ and $y$ coordinates. Lines starting with `|%|' or `|#|' are ignored. Such files are often generated by \textsc{gnuplot}: -\begin{codeexample}[code only] -#Curve 0, 20 points -#x y type -0.00000 0.00000 i -0.52632 0.50235 i -1.05263 0.86873 i -1.57895 0.99997 i -... -9.47368 -0.04889 i -10.00000 -0.54402 i -\end{codeexample} -This listing has been copied from~\cite[section~16.4]{tikz}. - -Plot file accepts one optional argument, - -\begin{codeexample}[code only] -\addplot file[skip first] {datafile.dat}; -\end{codeexample} - -\noindent -which allows to skip over a non-comment header line. This allows to read the same input files as |plot table| by skipping over column names. Please note that comment lines do not count as lines here. - -The input method |plot file| can also read meta data for every coordinate. As already explained for |plot coordinates| (see above), meta data can be used to change colors or other style parameters for every marker separately. Now, if |scatter src| is set to |explicit| or to |explicit symbolic| and the input method is |plot file|, one further element will be read from disk - for every line. Meta data is always the last element which is read. See page~\pageref{pgfplots:scatter:src} for information and examples about per point meta data and page~\pageref{pgfplots:scatterclasses} for an application example using |scatter/classes|. - - -Plot file is very similar to |plot table|: you can achieve the same effect with -\begin{codeexample}[code only] -\addplot table[x index=0,y index=0,header=false] {datafile.dat}; -\end{codeexample} -\noindent Due to its simplicity, |plot file| is slightly faster while |plot table| allows higher flexibility. - -Technical note: every opened file will be protocolled into your log file. -\end{addplotoperation} - -\subsubsection{Reading Coordinates From Tables} - -\begin{addplotoperation}[]{table}{\oarg{column selection}\marg{file}} -\PGFPlots\ comes with a new plotting command, the `|plot table|' macro. It's usage is similar in spirit to `|plot file|', but its flexibility is higher. Given a data file like -\begin{codeexample}[code only] -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{codeexample} -one may want to plot `|dof|' versus `|L2|' or `|dof|' versus `|Lmax|'. This can be done by -\begin{codeexample}[code only] -\begin{tikzpicture} -\begin{loglogaxis}[ - xlabel=Dof, - ylabel=$L_2$ error] -\addplot table[x=dof,y=L2] {datafile.dat}; -\end{loglogaxis} -\end{tikzpicture} -\end{codeexample} -or -\begin{codeexample}[code only] -\begin{tikzpicture} -\begin{loglogaxis}[ - xlabel=Dof, - 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: -\begin{codeexample}[code only] -\pgfplotstableread{datafile.dat}\table -... -\addplot table[x=dof,y=L2] from \table; -... -\addplot table[x=dof,y=Lmax] from \table; -... -\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: -\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 more than~$200$ data points (rows), you should always use file input (and reload if necessary). -\end{enumerate} - -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] -\addplot table[x index=2,y index=3] {datafile.dat}; -\addplot table[x=dof,y index=2] {datafile.dat}; -\end{codeexample} - -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 It is possible to read error coordinates from tables as well. Simply add options `|x error|', `|y error|' or `|x error index|'/`|y error index|' to \marg{source columns}. See section~\ref{sec:errorbars} for details about error bars. - \item It is possible to read per point meta data (usable in |scatter src|, see page~\pageref{pgfplots:scatter:src}) as has been discussed for |plot coordinates| and |plot file| above. The meta data column can be provided using the |meta| key (or the |meta index| key). - \item Use |plot table[|\meta{source columns}|] from |\marg{\textbackslash macro} to use a pre--read table. Tables can be read using -\begin{codeexample}[code only] -\pgfplotstableread{datafile.dat}\macroname. -\end{codeexample} - The keyword `|from|' can be omitted. - - \item The accepted input format of those tables is as follows: - \begin{itemize} - \item Columns are usually separated by white spaces (at least one tab or space). - - If you need other column separation characters, you can use the - - \declare{col sep}|=|\mchoice{space,comma,colon,semicolon,braces} - - 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. - \item The first line will be checked if it contains numerical data. If there is a column in the first line which is \emph{no} number, the complete line is considered to be a header which contains column names. Otherwise it belongs to the numerical data and you need to access column indices instead of names. - - \item There is future support for a second header line which must start with `|$flags |'. Currently, such a line is ignored. It may be used to provide number formatting hints like precision and number format if those tables shall be typeset using |\pgfplotstabletypeset| (see the manual for \PGFPlotstable). - \item The accepted number format is the same as for `|plot coordinates|', see above. - \item If you omit column selectors, the default is to plot the first column against the second. That means |plot table| does exactly the same job as |plot file| for this case. - \end{itemize} - \item It \emph{is} possible to create new columns out of existing ones, see the \PGFPlotstable\ manual section ``Postprocessing Data in New Columns''. - - In this context, you should consider using the key |read completely|, see below. - \item Technical note: every opened file will be protocolled into your log file. -\end{itemize} -\end{addplotoperation} - -\begin{pgfplotskey}{table/header=\mchoice{true,false} (initially true)} - Allows to disable header identification for |plot table|. See above. -\end{pgfplotskey} -\begin{pgfplotsxykeylist}{table/\x=\marg{column name}, - table/\x\ index=\marg{column index}} - These keys define the sources for |plot table|. If both, column names and column indices are given, column names are preferred. Column indexing starts with~$0$. The initial setting is to use |x index=0| and |y index=1|. - - Please note that column \emph{aliases} will be considered if unknown column names are used. Please refer to the manual of \PGFPlotstable\ which comes with this package. -\end{pgfplotsxykeylist} -\begin{pgfplotsxykeylist}{% - table/\x\ error=\marg{column name}, - table/\x\ error index=\marg{column index}} - These keys define input sources for error bars with explicit error values. Please see section~\ref{sec:errorbars} for details. -\end{pgfplotsxykeylist} -\begin{pgfplotsxykeylist}{% - table/meta=\marg{column name}, - table/meta index=\marg{column index}} - These keys define input sources for per point meta data. Please see page~\pageref{pgfplots:scatter:src} for details about meta data or the documentation for |plot coordinates| and |plot file| for further information. -\end{pgfplotsxykeylist} -\begin{key}{/pgfplots/table/col sep=\mchoice{space,comma,semicolon,colon,braces} (initially space)} - Allows to choose column separators for |plot table|. Please refer to the manual of \PGFPlotstable\ which comes with this package for details about |col sep|. -\end{key} -\begin{key}{/pgfplots/table/read completely=\marg{true,false} (initially false)} - Allows to customize |\addplot table|\marg{file name} such that it always reads the entire table into memory. - - This key has just one purpose, namely to create postprocessing columns on-the-fly and to plot those columns afterwards. This ``lazy evaluation'' which creates missing columns on-the-fly is documented in the \PGFPlotstable\ manual (in section ``Postprocessing Data in New Columns''). - - \paragraph{Attention:} Usually, |\addplot table| only picks required entries, requiring linear runtime complexity. As soon as |read completely| is activated, tables are loaded completely into memory. Due to datastructures issues (``macro append runtime''), the runtime complexity for |read completely| is $O(N^2)$ where $N$ is the number of rows. Thus: use this feature only for ``small'' tables. -\end{key} - -\subsubsection{Computing Coordinates with Mathematical Expressions} - -\begin{addplotoperation}[]{expression \marg{math expr}}{} - This input method allows to provide mathematical expressions which will be sampled. But unlike |plot gnuplot|, the expressions are evaluated using the math parser of \PGF, no external program is required. - - Plot expression samples |x| from the interval $[a,b]$ where $a$ and $b$ are specified with the |domain| key. The number of samples can be configured with |samples=|\meta{N} as for plot gnuplot. - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} - \addplot expression {x^2 + 4}; - \addplot expression {-5*x^3 - x^2}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -Please note that \PGF's math parser uses degrees for trigonometric functions: -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} - \addplot expression[domain=0:360] - {sin(x)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\noindent If you want to use radians, use -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} - \addplot expression[domain=-pi:pi] - {sin(deg(x))}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\noindent to convert the radians to degrees. The plot expression parser also accepts some more options like |samples at=|\marg{coordinate list} or |domain=|\meta{first}|:|\meta{last} which are described below. - -\paragraph{Remarks} -\begin{enumerate} - \item What really goes on is a loop which assigns the current sample coordinate to the macro |\x|. \PGFPlots\ defines a math constant |x| which always has the same value as |\x|. - - In short: it is the same whether you write |\x| or just |x| inside of math expressions. - - The variable name can be customized using |variable=\t|, for example. Then, |x| will be the same as |\t| (there won't be a short-hand name for user defined variable names). -\index{x@\texttt{\textbackslash x} In Coordinate Expressions}% -%\index{y@\texttt{\textbackslash y} In Coordinate Expressions}% - - \item The complete set of math expressions can be found in the \PGF\ manual. The most important mathematical operations are - |+|, |-|, |*|, |/|, |abs|, |round|, |floor|, |mod|, |<|, |>|, |max|, |min|, |sin|, |cos|, |tan|, |deg| (conversion from radians to degrees), |rad| (conversion from degrees to radians), |atan|, |asin|, |acos|, |cot|, |sec|, |cosec|, |exp|, |ln|, |sqrt|, the constanst |pi| and |e|, |^| (power operation), |factorial|\footnote{Starting with \PGF\ versions newer than $2.00$, you can use the postfix operator \texttt{!} instead of \texttt{factorial}.}, |rand| (random between $-1$ and $1$), |rnd| (random between $0$ and $1$), number format conversions |hex|, |Hex|, |oct|, |bin| and some more. The math parser has been written by Mark Wibrow and Till Tantau~\cite{tikz}, the FPU routines have been developed as part of \PGFPlots. The documentation for both parts can be found in~\cite{tikz}. - - Please note, however, that trigonometric functions are defined in degrees. The character `|^|' is used for exponentiation (not `|**|' as in gnuplot). - - \item If the $x$ axis is logarithmic, samples will be drawn logarithmically. - - \item Please note that plot expression does not allow per point meta data. -\end{enumerate} - -\paragraph{About the precision and number range:} -\index{Accuracy!High Precision for Plot Expression}% -\index{Errors!dimension too large}% - \index{Precision}\index{Floating Point Unit} Starting with version 1.2, |plot expression| uses a floating point unit. The FPU provides the full data range of scientific computing with a relative precision between $10^{-4}$ and $10^{-6}$. The |/pgf/fpu| key provides some more details. - - In case the |fpu| does not provide the desired mathematical function or is too slow\footnote{Or in case you find a bug$\dotsc$}, you should consider using the |plot gnuplot| method which invokes the external, freely available program |gnuplot| as desktop calculator. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{loglogaxis}[ - title={$\frac{1}{x^2}$}] - \addplot[blue] - expression[domain=1:1e30] - {x^-2}; - \end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{semilogyaxis}[ - title={$e^x$ logarithmically plotted}] - \addplot[blue] - expression[domain=1:700] - {exp(x)}; - \end{semilogyaxis} -\end{tikzpicture} -\end{codeexample} -\end{addplotoperation} - -\begin{addplotoperation}[]{\marg{math expression}}{} - Use - - |\addplot |\marg{math expression}|;| - - as short-hand equivalent for - - |\addplot expression |\marg{math expression}|;| -\end{addplotoperation} - -\begin{addplotoperation}[]{(\meta{$x$ expression},\meta{$y$ expression})}{} - A variant of |\addplot expression| which allows to provide different coordinate expressions for the $x$ and $y$ coordinates. This can be used to generate parameterized plots. - - Please note that |\addplot (\x,\x^2)| is equivalent to |\addplot expression {\x^2}|. - - Note further that since the complete point expression is surrounded by round braces, you can't use round braces for either \meta{$x$ expression} or \meta{$y$ expression}. You will need to introduce curly braces additionally to round braces. -\end{addplotoperation} - -\begin{key}{/pgfplots/domain=\meta{start}:\meta{end} (initially [-5:5])} - Determines the plotted range. This is not necessarily the same as the axis limits (which are configured with the |xmin|/|xmax| options). - - This option is used for |plot expression| and for |plot gnuplot|. - - The |domain| key won't be used if |samples at| is specified; |samples at| has higher precedence. - - \paragraph{Remark for \Tikz-users:} |/pgfplots/domain| and |/tikz/domain| are independent options. Please prefer the \PGFPlots\ variant (i.e. provide |domain| to an axis, |\pgfplotsset| or a plot command). Since older versions also accepted something like |\begin{tikzpicture}[domain=|$\dotsc$|]|, this syntax is also accepted as long as no \PGFPlots\ |domain| key is set. -\end{key} - -\begin{key}{/pgfplots/samples=\marg{number} (initially 25)} - Sets the number of sample points for |plot expression| and |plot gnuplot|. - - The |samples| key won't be used if |samples at| is specified; |samples at| has higher precedence. - - The same special treatment of |/tikz/samples| and |/pgfplots/samples| as for the |domain| key applies here. See above for details. -\end{key} - -\begin{pgfplotskey}{samples at=\marg{coordinate list}} - Sets the $x$ coordinates for |plot expression| explicitly. This overrides |domain| and |samples|. - - The \marg{coordinate list} is a |\foreach| expression, that means it can contain a simple list of coordinates (comma--separated) but also complex |...| expressions like\footnote{Unfortunately, the |...| is somewhat restrictive when it comes to extended accuracy. So, if you have particularly small or large numbers (or a small distance), you have to provide a comma--separated list (or use the \texttt{domain} key).} -\begin{codeexample}[code only] -\pgfplotsset{samples at={5e-5,7e-5,10e-5,12e-5}} -\pgfplotsset{samples at={-5,-4.5,...,5}} -\pgfplotsset{samples at={-5,-3,-1,-0.5,0,...,5}} -\end{codeexample} - - The same special treatment of |/tikz/samples at| and |/pgfplots/samples at| as for the |domain| key applies here. See above for details. - - \paragraph{Attention:} |samples at| overrides |domain|, even if |domain| has been set \emph{after} |samples at|! Use |samples at={}| to clear \marg{coordinate list} and re-activate |domain|. -\end{pgfplotskey} - -\subsubsection{Computing Coordinates with Mathematical Expressions (gnuplot)} - -\begin{addplotoperation}[]{gnuplot}{\marg{gnuplot code}} -In contrast to |plot expression|, the |plot gnuplot| command employs the external program |gnuplot| to compute coordinates. The resulting coordinates are written to a text file which will be plotted with |plot file|. \PGF\ checks whether coordinates need to be re-generated and calls |gnuplot| whenever necessary (this is usually the case if you change the number of samples, the argument to |plot gnuplot| or the plotted domain\footnote{Please note that \PGFPlots\ produces slightly different files than \Tikz\ when used with |plot gnuplot| (it configures high precision output). You should use different ids to avoid conflicts in such a case.}). - -The differences between |plot expression| and |plot gnuplot| are: -\begin{itemize} - \item |plot expression| does not require any external programs and requires no additional command line options. - \item |plot expression| does not produce a lot of temporary files. - \item |plot gnuplot| uses radians for trigonometric functions while |plot expression| has degrees. - \item |plot gnuplot| is faster. - \item |plot gnuplot| has a larger mathematical library. - \item |plot gnuplot| has a higher accuracy. However, starting with version 1.2, this is no longer a great problem. The new floating point unit for \TeX\ provides reasonable accuracy and the same data range as |gnuplot|. -\end{itemize} - -Since system calls are a potential danger, they need to be enabled explicitly using command line options, for example -\begin{codeexample}[code only] -pdflatex -shell-escape filename.tex. -\end{codeexample} -Sometimes it is called |shell-escape| or |enable-write18|. Sometimes one needs two slashes -- that all depends on your \TeX\ distribution. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot plot[id=sin] - gnuplot{sin(x)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{semilogyaxis} -\addplot plot[id=exp,domain=0:10] - gnuplot{exp(x)}; -\end{semilogyaxis} -\end{tikzpicture} -\end{codeexample} - -The \meta{style options} determine the appearance of the plotted function; these parameters also affect the legend. The \meta{behavior options} are specific to the gnuplot interface. These options are described in all detail in \cite[section~18.6]{tikz}. A short summary is shown below. - -Please note that |plot gnuplot| does not allow per point meta data. - -Please refer to \cite[section~18.6]{tikz} for more details about |plot function| and the |gnuplot| interaction. -\end{addplotoperation} - -\begin{addplotoperation}[]{function}{\marg{gnuplot code}} - Use - - |\addplot function |\marg{gnuplot code}|;| - - as alias for - - |\addplot gnuplot |\marg{gnuplot code}|;| -\end{addplotoperation} - -\begin{key}{/tikz/id=\marg{unique string identifier}} - A unique identifier for the current plot. It is used to generate temporary filenames for |gnuplot| output. -\end{key} - -\begin{key}{/tikz/prefix=\marg{file name prefix}} - A common path prefix for temporary filenames (see \cite[section~18.6]{tikz} for details). -\end{key} - -\begin{key}{/tikz/raw gnuplot} - Disables the use of |samples| and |domain|. -\end{key} - -\subsubsection{Using External Graphics as Plot Sources} - -\begin{addplotoperation}[]{graphics}{\marg{file name}} - This plot type allows to extend the plotting capabilities of \PGFPlots\ beyond its own limitations. The idea is to generate the graphics as such (for example, a contour plot, a shaded surface or a large point cluster) with an external program like Matlab (tm) or |gnuplot|. The graphics, however, should \emph{not} contain an axis or descriptions. Then, we use |\includegraphics| and an \PGFPlots\ axis which fits exactly on top of the imported graphics. - - Of course, one could do this manually by providing proper scales and such. The operation |plot graphics| is intended so simplify this process. However the \emph{main difficulty} is to get images with correct bounding box. Typically, you will have to adjust bounding boxes manually. - - Let's start with an example: Suppose we use, for example, matlab to generate a surface plot like -\begin{codeexample}[code only] -[X,Y] = meshgrid( linspace(-3,3,500) ); -surf( X,Y, exp(-(X - Y).^2 - X.^2 ) ); -shading flat; view(0,90); axis off; -print -dpng external1 -\end{codeexample} - \noindent which is then found in |external1.png|. The |surf| command of Matlab generates the surface, the following commands disable the axis descriptions, initialise the desired view and export it. Viewing the image in any image tool, we see a lot of white space around the surface -- Matlab has a particular weakness in producing tight bounding boxes, as far as I know. Well, no problem: use your favorite image editor and crop the image (most image editors can do this automatically). We could use the free ImageMagick command - - |convert -trim external1.png external1.png| - - to get a tight bounding box. Then, we use - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[enlargelimits=false,axis on top] - \addplot graphics - [xmin=-3,xmax=3,ymin=-3,ymax=3] - {external1}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\noindent to load the graphics\footnote{Please note that I don't have a Matlab license, so I used \texttt{gnuplot} to produce an equivalent replacement graphics.} just as if we would have drawn it with \PGFPlots. The |axis on top| simply tells \PGFPlots\ to draw the axis on top of any plots (see its description). - -Our first test was successful -- and not difficult at all because graphics programs can automatically compute the bounding box. There are a couple of free tools available which can compute tight bounding boxes for |.eps| or |.pdf| graphics: -\begin{enumerate} - \item The free vector graphics program |inkscape| can help here. Its feature ``File $\gg$ Document Properties: Fit page to selection'' computes a tight bounding box around every picture element. - - However, some images may contain a rectanglar path which is as large as the bounding box (Matlab (tm) computes such |.eps| images). In this case, use the ``Ungroup'' method as often as necessary and remove such a path. - - Finally, save as |.eps|. - - However, |inkscape| appears to have problems with postscript fonts -- it substitutes them. This doesn't pose problems in this application because fonts shouldn't be part of such images -- the descriptions will be drawn by \PGFPlots. - - \item The tool |pdfcrop| removes surrounding whitespace in |.pdf| images and produces quite good bounding boxes. -\end{enumerate} - -\paragraph{Adjusting bounding boxes manually} -In case you don't have tools at hand to provide correct bounding boxes, you can still use \TeX\ to set the bounding box manually. Some viewers like |gv| provide access to low--level image coordinates. The idea is to determine the number of units which need to be removed and communicate these units to |\includegraphics|. - -Let's follow this approach in a further example. - - We use |gnuplot| to draw a (relatively stupid) example data set. The gnuplot script -\begin{codeexample}[code only] -set samples 30000 -set parametric -unset border -unset xtics -unset ytics -set output "external2.eps" -set terminal postscript eps color -plot [t=0:1] rand(0),rand(0) with dots notitle lw 5 -\end{codeexample} -\noindent generates |external2.eps| with a uniform random sample of size $30000$. As before, we import this scatter plot into \PGFPlots\ using |plot graphics|. Again, the bounding box is too large, so we need to adjust it (|gnuplot| can do this automatically, but we do it anyway to explain the mechanisms): - -Using |gv|, I determined that the bounding box needs to be shifted |12| units to the left and |9| down. Furthermore, the right end is |12| units too far off and the top area has about |8| units space wasted. This can be provided to the |trim| option of |\includegraphics|, and we use |clip| to clip the rest away: -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[axis on top,title=Graphics Import] - \addplot 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)}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - - So, |plot graphics| takes a graphics file along with options which can be passed to |\includegraphics|. Furthermore, it provides the information how to embed the graphics into an axis. The axis can contain any other |\addplot| command as well and will be resized properly. - - -\paragraph{Details about \texttt{plot graphics}:} - The loaded graphics file is drawn with - - |\node[/pgfplots/plot graphics/node] {\includegraphics[|\meta{options}|]|\marg{file name}|};| - - where the |node| style is a configurable style. The node is placed at the coordinate designated by |xmin|, |ymin|. - - 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. -\end{addplotoperation} -\begin{pgfplotsxykeylist}{ - plot graphics/\x min=\marg{coordinate}, - plot graphics/\x max=\marg{coordinate}} - These keys are required for |plot graphics| and provide information about the external data range. The graphics will be squeezed between these coordinates. -\end{pgfplotsxykeylist} -\begin{pgfplotskey}{plot graphics/includegraphics=\marg{options}} - A list of options which will be passed as--is to |\includegraphics|. Interesting options include the |trim=|\meta{left} \meta{bottom} \meta{right} \meta{top} key which reduces the bounding box and |clip| which discards everything outside of the bounding box. The scaling options won't have any effect, they will be overwritten by \PGFPlots. -\end{pgfplotskey} -\begin{stylekey}{/pgfplots/plot graphics/node} - A predefined style used for the node containing the graphics. The predefined value is -\begin{codeexample}[code only] -\pgfplotsset{ - plot graphics/node/.style={ - transform shape, - inner sep=0pt, - outer sep=0pt, - every node/.style={}, - anchor=south west, - at={(0pt,0pt)}, - rectangle - } -} -\end{codeexample} -\end{stylekey} -\begin{pgfplotskey}{plot graphics} - This key belongs to the public low--level plotting interface. You won't need it in most cases. - - This key is similar to |sharp plot| or |smooth| or |const plot|: it installs a low--level plot--handler which expects exactly two points: the lower left corner and the upper right one. The graphics will be drawn between them. The graphics file name is expected as value of the |/pgfplots/plot graphics/src| key. The other keys described above need to be set correctly (excluding the limits, these are ignored at this level of abstraction). This key can be used independent of an axis. -\end{pgfplotskey} - -\begin{command}{\addplot+\oarg{style options} \textcolor{gray}{\dots};} -Does the same like |\addplot[|\meta{style options}|] ...;| except that \meta{style options} is \emph{appended} to the arguments which would have been taken for |\addplot ...| (the element of the default list). - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot {sin(deg(x))}; -\end{axis} -\end{tikzpicture} - -\begin{tikzpicture} -\begin{axis} -\addplot+[only marks] {sin(deg(x))}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{command} - -\subsection{Accessing Axis Coordinates for Annotations} -\label{sec:axis:coords}% -\begin{coordinatesystem}{axis cs} -\PGFPlots\ provides a new coordinate system for use inside of an axis, the ``axis coordinate system'', |axis cs|. - -It can be used to draw any \Tikz-graphics at axis coordinates. It is used like -\begin{codeexample}[code only] -\draw - (axis cs:18943,2.873391e-05) -|- (axis cs:47103,8.437499e-06); -\end{codeexample} -\begin{codeexample}[] -\tikzstyle{every pin}=[fill=white, - draw=black, - font=\footnotesize] -\begin{tikzpicture} - \begin{loglogaxis}[ - xlabel={\textsc{Dof}}, - ylabel={$L_2$ Error}] - - \addplot coordinates { - (11, 6.887e-02) - (71, 3.177e-02) - (351, 1.341e-02) - (1471, 5.334e-03) - (5503, 2.027e-03) - (18943, 7.415e-04) - (61183, 2.628e-04) - (187903, 9.063e-05) - (553983, 3.053e-05) - }; - - \node[coordinate,pin=above:{Bad!}] - at (axis cs:5503,2.027e-03) {}; - \node[coordinate,pin=left:{Good!}] - at (axis cs:187903,9.063e-05) {}; - \end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{loglogaxis}[ - xlabel=\textsc{Dof}, - ylabel=$L_2$ Error -] -\draw - (axis cs:1793,4.442e-05) - |- (axis cs:4097,1.207e-05) - node[near start,left] - {$\frac{dy}{dx} = -1.58$}; - -\addplot coordinates { - (5, 8.312e-02) - (17, 2.547e-02) - (49, 7.407e-03) - (129, 2.102e-03) - (321, 5.874e-04) - (769, 1.623e-04) - (1793, 4.442e-05) - (4097, 1.207e-05) - (9217, 3.261e-06) -}; -\end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - -\paragraph{Attention:} Whenever you draw additional graphics, consider using |axis cs|! It applies any logarithms, data scaling transformations or whatever \PGFPlots\ usually does! -\end{coordinatesystem} - -\begin{predefinednode}{current plot begin} - This coordinate will be defined for every plot and can be used is \meta{trailing path commands} or after a plot. It is the first coordinate of the current plot. -\end{predefinednode} - -\begin{predefinednode}{current plot end} - This coordinate will be defined for every plot. It is the last coordinate of the current plot. -\end{predefinednode} - -\subsection{Legend Commands} -\label{pgfplots:sec:legendcmds} - -\begin{command}{\addlegendentry\marg{name}} -Adds a single legend entry to the legend list. This will also enable legend drawing. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot[smooth,mark=*,blue] coordinates { - (0,2) - (2,3) - (3,1) -}; -\addlegendentry{Case 1} - -\addplot[smooth,color=red,mark=x] - coordinates { - (0,0) - (1,1) - (2,1) - (3,2) - }; -\addlegendentry{Case 2} -\end{axis} -\end{tikzpicture} -\end{codeexample} -It does not matter where |\addlegendentry| commands are placed, only the sequence matters. You will need one |\addlegendentry| for every |\addplot| command. - - -Optional argument are accepted with|\addlegendentry|\oarg{key-value-list}|{...}|. This does mainly affect some keys affecting the legend layout, support is very limited. - -Using |\addlegendentry| disables the key |legend entries|. -\end{command} - - - -\label{sec:legenddef}% -\begin{command}{\legend\marg{list}} -You can use |\legend|\marg{list} to assign a complete legend. -\begin{codeexample}[code only] -\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} -\end{codeexample} -The argument of |\legend| is a comma--separated list of entries, one for each plot. It is processed using the \PGF-foreach command\footnote{Older versions of \PGFPlots\ used \texttt{\textbackslash legend\{first\textbackslash\textbackslash second\textbackslash\textbackslash third\textbackslash\textbackslash\}} instead of comma--separated lists. This syntax is still accepted.}. -The short marker/line combination shown in legends is acquired from the \marg{style options} argument of |\addplot|. - -Using |\legend| overwrites any other existing legend entries. -\end{command} - -\subsubsection{Legend Appearance} -The legend appearance can be configured with the help of several styles and options. These options are described in section~\ref{pgfplots:sec:legendopts}, under Axis Descriptions. - -\subsubsection{\texttt{\textbackslash label} and \texttt{\textbackslash ref} for Legend Creation} -\PGFPlots\ offers a |\label| and |\ref| feature for \LaTeX\ to assemble a legend manually, for example as part of the figure caption. These references work as usual \LaTeX\ references: a |\label| remembers where and what needs to be referenced and a |\ref| expands to proper text. In context of plots, a |\label| remembers the plot specification of one plot and a |\ref| expands to the small image which would also be used inside of legends. -\begin{codeexample}[] -\begin{tikzpicture}[baseline] -\begin{axis} - \addplot+[only marks] - expression[samples=15, - error bars/y dir=both, - error bars/y fixed=2.5] - {3*x+2.5*rand}; - \label{pgfplots:label1} - - \addplot+[mark=none] {3*x}; - \label{pgfplots:label2} - - \addplot {4*cos(deg(x))}; - \label{pgfplots:label3} -\end{axis} -\end{tikzpicture} -\end{codeexample} -\begin{codeexample}[code only] -The picture shows the estimations \ref{pgfplots:label1} which are subjected to noise. -It appears the model \ref{pgfplots:label2} fits the data appropriately. -Finally, \ref{pgfplots:label3} is only here to get three examples. -\end{codeexample} -\noindent The picture shows the estimations \ref{pgfplots:label1} which are subjected to noise. -It appears the model \ref{pgfplots:label2} fits the data appropriately. -Finally, \ref{pgfplots:label3} is only here to get three examples. - -\begin{command}{\label\marg{label name}} - When used after |\addplot|, this command creates a \LaTeX\ label named \marg{label name}\footnote{This feature is \emph{only} available in \LaTeX, sorry.}. If this label is cross-referenced with |\ref|\marg{label name} somewhere, the associated plot specification will be inserted. -\begin{codeexample}[] -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 independant 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.}. - - More precisely, the small image generated by |\ref|\marg{label name} is -\begin{codeexample}[code only] -\tikz[/pgfplots/every crossref picture] {...} -\end{codeexample} - \noindent where the contents is determined by |legend image code| and the plot style. -\end{command} - -\begin{command}{\ref\marg{label name}} - Can be used to reference a labeled, single plot. See the example above. - - This will also work together with |hyperref| links and |\pageref|. -\end{command} - -\begin{key}{/pgfplots/refstyle=\marg{label name}} - Can be used to set the \emph{styles} of a labeled, single plot. This allows to write -\begin{codeexample}[code only] -\addplot[/pgfplots/refstyle={pgfplots:label2}] -\end{codeexample} - \noindent somewhere. Please note that it may be easier to define a style with |.style|. -\end{key} - -\begin{stylekey}{/pgfplots/every crossref picture} - A style which will be used by the cross-referencing feature for plots. The default is -\begin{codeexample}[code only] -\pgfplotsset{every crossref picture/.style={baseline,yshift=0.3em}} -\end{codeexample} -\end{stylekey} - - -\subsection{Closing Plots} -\begin{command}{\closedcycle} - Provide |\closedcycle| as \meta{trailing path commands} after |\addplot| to draw a closed line from the last plot coordinate to the first one. - - Use |\closedcycle| whenevery you intend to fill the area under a plot. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis} - \addplot {x^2+2} \closedcycle; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis} - \addplot+[fill] {x^2+2} \closedcycle; - \end{axis} -\end{tikzpicture} -\end{codeexample} - In case of stacked plots, |\closedcycle| connects the current plot with the previous plot instead of connecting with the $x$~axis\footnote{The implementation for stacked plots requires some additional logic to determine the filled area: \lstinline{\\closedcycle} will produce a |plot coordinates| command with \emph{reversed} coordinates of the previous plot. This is usually irrelevant for end users, but it assumes that the plot's type is symmetric. Since constant plots are inherently unsymmetric, \lstinline{\\closedcycle} will use \texttt{const plot mark right} as reversed sequence for \texttt{const plot mark left}.}. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[stack plots=y] - \addplot+[fill] coordinates - {(0,1) (1,1) (2,2) (3,2)} \closedcycle; - \addplot+[fill] coordinates - {(0,1) (1,1) (2,2) (3,2)} \closedcycle; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\end{command} - -\subsection{Other Commands} -\begin{command}{\autoplotspeclist} -This command should no longer be used, although it will be kept as technical implementation detail. Please use the `|cycle list|' option, section~\ref{sec:cycle:list}. -\end{command} - -\begin{command}{\pgfmathlogtologten\meta{number}} -Assigns the result of $\meta{number}/\log(10)$ to |\pgfmathresult|. -\end{command} - -\begin{command}{\logten} -Expands to the constant $\log(10)$. Useful for logplots because $\log(10^i) = i\log(10)$. This command is only available inside of an \Tikz-picture. -\end{command} - -\begin{command}{\pgfmathprintnumber\marg{number}} -Generates pretty--printed output\footnote{This method was previously \texttt{\textbackslash prettyprintnumber}. It's functionality has been included into \PGF\ and the old command is now deprecated.} for \marg{number}. This method is used for every tick label. - -The number is printed using the current number printing options, see section~\ref{sec:number:printing} for the different number styles, rounding precision and rounding methods. -\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. -\end{command} - -\begin{command}{\coordindex} - Inside of an |\addplot| command, this macro expands to the number of the actual coordinate (starting with~$0$). - - It is useful together with |x filter| or |y filter| to (de-)select coordinates. -\end{command} - -\begin{command}{\pgfplotstableread\marg{file}} - Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle. -\end{command} -\begin{command}{\pgfplotstabletypeset\marg{\textbackslash macro}} - Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle. -\end{command} - -\section{Option Reference} -There are several required and even more optional arguments to modify axes. They are used like -\begin{codeexample}[code only] -\begin{tikzpicture} -\begin{axis}[key=value,key2=value2] -... -\end{axis} -\end{tikzpicture} -\end{codeexample} -\noindent -The overall appeareance can be changed with -\begin{codeexample}[code only] -\pgfplotsset{every axis/.append style={line width=1pt}} -\end{codeexample} -\noindent -for example. There are several other styles predefined to modify the appearance, see section~\ref{sec:styles}. - -\begin{command}{\pgfplotsset\marg{key-value-list}} - Defines or sets all options in \marg{key-value-list}. - - It is a shortcut for |\pgfqkeys{/pgfplots}|\marg{key-value-list}, that means it inserts the prefix |/pgfplots| to any option which has no full path. - - This command can be used to define default options for the complete document or a part of the document. For example, -\begin{codeexample}[code only] -\pgfplotsset{ - cycle list={% - {red, mark=*}, {blue,mark=*}, - {red, mark=x}, {blue,mark=x}, - {red, mark=square*}, {blue,mark=square*}, - {red, mark=triangle*}, {blue,mark=triangle*}, - {red, mark=diamond*}, {blue,mark=diamond*}, - {red, mark=pentagon*}, {blue,mark=pentagon*} - }, - legend style={ - at={(0.5,-0.2)}, - anchor=north, - legend columns=2, - cells={anchor=west}, - font=\footnotesize, - rounded corners=2pt, - }, - xlabel=$x$,ylabel=$f(x)$ -} -\end{codeexample} - can be used to set document--wise styles for line specifications, the legend's style and axis labels. - - You can also define new styles (collections of key--value--pairs) with |.style| and |.append style|. -\begin{codeexample}[code only] -\pgfplotsset{ - My Style 1/.style={xlabel=$x$, legend entries={1,2,3} }, - My Style 2/.style={xlabel=$X$, legend entries={4,5,6} } -\end{codeexample} - The |.style| and |.append style| key handlers are described in section~\ref{sec:styles} in more detail. -\end{command} - - -\subsection{Pgfplots Options and \Tikz\ Options} -This section is more or less technical and can be skipped unless one really wants to know more about this topic. - -\Tikz\ options and \PGFPlots\ options can be mixed inside of the axis arguments and in any of the associated styles. For example, -\begin{codeexample}[code only] -\pgfplotsset{every axis legend/.append style={ - legend columns=3,font=\Large}} -\end{codeexample} -\noindent -assigns the `|legend columns|' option (a pgfplots option) and uses `|font|' for drawing the legend (a \Tikz\ option). - -The axis environments will process any known pgfplots options, and all `|every|'--styles will be parsed for pgfplots options. Every unknown option is supposed to be a \Tikz\ option and will be forward to the associated \Tikz\ drawing commands. For example, the `\lstinline{font=\Large}' above will be used as argument to the legend matrix, and the `\lstinline{font=\Large}' argument in -\begin{codeexample}[code only] -\pgfplotsset{every axis label/.append style={ - ylabel=Error,xlabel=Dof,font=\Large}} -\end{codeexample} -will be used in the nodes for axis labels (but not the axis title, for example). - -It is an error if you assign incompatible options to axis labels, for example `|xmin|' and `|xmax|' can't be set inside of `|every axis label|'. - - -\subsection{Plot Types} -\PGFPlots\ supports several two-dimensional line-plots like piecewise linear line plots, piecewise constant plots, smoothed plots, bar plots and comb plots. Most of them use the \PGF\ plot handler library directly, see \cite[section 18.8]{tikz}. - -Plot types are part of the plot style, so they are set with options. The following list contains a short summary of the \PGF\ plot library, \cite[section 18.8]{tikz}. - - -\subsubsection{Linear Plots} -\begin{plottype}{sharp plot} -Linear (`sharp') plots are the default. Point coordinates are simply connected by straight lines. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} - \addplot+[sharp plot] coordinates - {(0,0) (1,2) (2,3)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -The `|+|' here means to use the normal plot cycle list and append `|sharp plot|' to its option list. -\end{plottype} - -\subsubsection{Smooth Plots} -\begin{plottype}{smooth} -Smooth plots interpolate smoothly between successive points. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} - \addplot+[smooth] coordinates - {(0,0) (1,2) (2,3)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{plottype} - -\subsubsection{Constant Plots} -Constant plots draw lines parallel to the $x$-axis to connect coordinates. The discontinuos edges may be drawn or not, and marks may be placed on left or right ends. - -\begin{plottype}{const plot} -Connects all points with horizontal and vertical lines. Marks are placed left-handed on horizontal line segments, causing the plot to be right-sided continuous at all data points. - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot+[const plot] -coordinates -{(0,0.1) (0.1,0.15) (0.2,0.5) (0.3,0.62) - (0.4,0.56) (0.5,0.58) (0.6,0.65) (0.7,0.6) - (0.8,0.58) (0.9,0.55) (1,0.52)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ymin=0,ymax=1,enlargelimits=false] -\addplot - [const plot,fill=blue,draw=black] -coordinates -{(0,0.1) (0.1,0.15) (0.2,0.5) (0.3,0.62) - (0.4,0.56) (0.5,0.58) (0.6,0.65) (0.7,0.6) - (0.8,0.58) (0.9,0.55) (1,0.52)} - \closedcycle; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{plottype} - -\begin{plottype}{const plot mark left} -An alias for `|const plot|'. -\end{plottype} - -\begin{plottype}{const plot mark right} - A variant which places marks on the right of each line segment, causing plots to be left-sided continuous at coordinates. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot+[const plot mark right] -coordinates -{(0,0.1) (0.1,0.15) (0.2,0.5) (0.3,0.62) - (0.4,0.56) (0.5,0.58) (0.6,0.65) (0.7,0.6) - (0.8,0.58) (0.9,0.55) (1,0.52)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{plottype} - -\begin{plottype}{jump mark left} -A variant of `|const plot mark left|' which does not draw vertical lines. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[samples=8] -\addplot+[jump mark left] - expression[domain=-5:0] - {4*x^2 - 5}; - -\addplot+[jump mark right] - expression[domain=-5:0] - {0.7*x^3 + 50}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{plottype} - -\begin{plottype}{jump mark right} -A variant of `|const plot mark right|' which does not draw vertical lines. -\end{plottype} - -\subsubsection{Bar Plots} -Bar plots place horizontal or vertical bars at coordinates. Multiple bar plots in one axis can be stacked on top of each other or aligned next to each other. - -\begin{plottype}{xbar} - Places horizontal bars between the $(y=0)$ line and each coordinate. - - This option is used on a per-plot basis and configures only the visualization of coordinates. The figure-wide style |/pgfplots/xbar| also sets reasonable options for ticks, legends and multiple plots. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot+[xbar] coordinates - {(4,0) (1,1) (2,2) - (5,3) (6,4) (1,5)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - Bars are centered at plot coordinates with width |bar width|. Using bar plots usually means more than just a different way of how to connect coordinates, for example to draw ticks outside of the axis, change the legend's appearance or introduce shifts if multiple |\addplot| commands appear. - - There is a preconfigured style for |xbar| which is installed automatically if you provide |xbar| as argument to the axis environment which provides this functionality. -% \usetikzlibrary{patterns} -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[xbar,enlargelimits=0.15] -\addplot -[draw=blue,pattern=horizontal lines light blue] -coordinates - {(10,5) (15,10) (5,15) (24,20) (30,25)}; - -\addplot -[draw=black,pattern=horizontal lines dark blue] -coordinates - {(3,5) (5,10) (15,15) (20,20) (35,25)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -Here |xbar| yields |/pgfplots/xbar| because it is an argument to the axis, not to a single plot. - - Besides line-, fill- and colorstyles, bars can be configured with |bar width| and |bar shift|, see below. -\end{plottype} - -\begin{stylekey}{/pgfplots/xbar=\marg{shift for multiple plots} (default 2pt)} - This style sets |/tikz/xbar| \emph{and} some commonly used options concerning horizontal bars for the complete axis. This is automatically done if you provide |xbar| as argument to an axis argument, see above. - -The |xbar| style defines shifts if multiple plots are placed into one axis. It draws bars adjacent to each other, separated by \marg{shift for multiple plots}. Furthermore, it sets the style |bar cycle list| and sets tick and legend appearance options. - -The style is defined as follows. -\begin{codeexample}[code only] -/pgfplots/xbar/.style={ - bar cycle list, - tick align=outside, - /pgfplots/legend image code/.code= - {\draw[##1,bar width=3pt,yshift=-0.2em,bar shift=0pt] - plot coordinates {(0cm,0.8em) (2*\pgfplotbarwidth,0.6em)};}, - /pgf/bar shift={% - % total width = n*w + (n-1)*skip - % -> subtract half for centering - -0.5*(\numplots*\pgfplotbarwidth + (\numplots-1)*#1) + - % the '0.5*w' is for centering - (.5+\plotnum)*\pgfplotbarwidth + \plotnum*#1}, - /tikz/xbar}, -\end{codeexample} -The formular for |bar shift| assigns shifts dependend on the total number of plots and the current plot's number. It is designed to fill a total width of $n \cdot $|bar width|$ + (n-1) \cdot $\marg{shift for multiple plots}. The $0.5$ compensates for centering. -\end{stylekey} - -\begin{plottype}{ybar} - Like |xbar|, this option generates bar plots. It draws vertical bars between the ($x=0$) line and each input coordinate. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot+[ybar] plot coordinates - {(0,3) (1,2) (2,4) (3,1) (4,2)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - The example above simply changes how input coordinates shall be visualized. As mentioned for |xbar|, one usually needs modified legends and shifts for multiple bars in the same axis. - - There is a predefined style which installs these customizations when provided to the axis-environment: -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - x tick label style={ - /pgf/number format/1000 sep=}, - ylabel=Population, - enlargelimits=0.15, - legend style={at={(0.5,-0.15)}, - anchor=north,legend columns=-1}, - ybar, - bar width=7pt, -] -\addplot - coordinates {(1930,50e6) (1940,33e6) - (1950,40e6) (1960,50e6) (1970,70e6)}; - -\addplot - coordinates {(1930,38e6) (1940,42e6) - (1950,43e6) (1960,45e6) (1970,65e6)}; - -\addplot - coordinates {(1930,15e6) (1940,12e6) - (1950,13e6) (1960,25e6) (1970,35e6)}; -\legend{Far,Near,Here} -\end{axis} -\end{tikzpicture} -\end{codeexample} -Here |ybar| yields |/pgfplots/ybar| because it is an argument to the axis, not to a single plot. - - As for |xbar|, the bar width and shift can be configured with |bar width| and |bar shift|. -\end{plottype} - -\begin{stylekey}{/pgfplots/ybar=\marg{shift for multiple plots} (default 2pt)} - As |/pgfplots/xbar|, this style sets the |/tikz/ybar| option to draw vertical bars, but it also provides commonly used options for vertical bars. - - If you supply |ybar| to an axis environment, |/pgfplots/ybar| will be chosen instead of |/tikz/ybar|. - - It changes the legend, draws ticks outside of the axis lines and draws multiple |\addplot| arguments adjacent to each other; block--centered at the $x$ coordinate and separated by \marg{shift for multiple plots}. Furthermore, it installs the style |bar cycle list|. It is defined similarly to |/pgfplots/xbar|. -\end{stylekey} - -\begin{key}{/tikz/bar width=\marg{dimension} (initially 10pt)} - Configures the width used by |xbar| and |ybar|. It is accepted to provide mathematical expressions. -\end{key} - -\begin{key}{/tikz/bar shift=\marg{dimension} (initially 0pt)} - Configures a shift for |xbar| and |ybar|. Use |bar shift| together with |bar width| to draw multiple bar plots into the same axis. It is accepted to provide mathematical expressions. -\end{key} - - -\begin{plottype}{ybar interval} - This plot type produces vertical bars with width (and shift) relatively to intervals of coordinates. - - It is installed on a per-plot basis and configures \emph{only} the visualization of coordinates. See the style |/pgfplots/ybar interval| which configures the appearance of the complete figure. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot+[ybar interval] plot coordinates - {(0,2) (0.1,1) (0.3,0.5) (0.35,4) (0.5,3) - (0.6,2) (0.7,1.5) (1,1.5)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ybar interval, - xtick=data, - xticklabel interval boundaries, - x tick label style= - {rotate=90,anchor=east} - ] -\addplot coordinates - {(0,2) (0.1,1) (0.3,0.5) (0.35,4) (0.5,3) - (0.6,2) (0.7,1.5) (1,1.5)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - x tick label style={ - /pgf/number format/1000 sep=}, - ylabel=Population, - enlargelimits=0.05, - legend style={at={(0.5,-0.15)}, - anchor=north,legend columns=-1}, - ybar interval=0.7, -] -\addplot - coordinates {(1930,50e6) (1940,33e6) - (1950,40e6) (1960,50e6) (1970,70e6)}; - -\addplot - coordinates {(1930,38e6) (1940,42e6) - (1950,43e6) (1960,45e6) (1970,65e6)}; - -\addplot - coordinates {(1930,15e6) (1940,12e6) - (1950,13e6) (1960,25e6) (1970,35e6)}; -\legend{Far,Near,Here} -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{plottype} - -\begin{stylekey}{/pgfplots/ybar interval=\marg{relative width} (default 1)} - A style which is intended to install options for |ybar interval| for a complete figure. This includes tick and legend appearance, management of multiple bar plots in one figure and a more adequate |cycle list| using the style |bar cycle list|. -\end{stylekey} - -\begin{plottype}{xbar interval} - As |ybar interval|, just for horizontal bars. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - xmin=0,xmax=53, - ylabel=Age, - xlabel=Quantity, - y label style={yshift=0.7cm}, - enlargelimits=false, - ytick=data, - yticklabel interval boundaries, - xbar interval, -] -\addplot - coordinates {(10,5) (10.5,10) (15,13) - (24,18) (50,21) (23,25) (10,30) - (3,50) (3,70)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{plottype} - -\begin{stylekey}{/pgfplots/xbar interval=\marg{relative width} (default 1)} - A style which is intended to install options for |xbar interval| for a complete figure, see the style |/pgfplots/ybar interval| for details. -\end{stylekey} - -\begin{pgfplotsxykey}{\x ticklabel interval boundaries} - These are style keys which set |x tick label as interval| and configure the tick appearance to be \marg{start} -- \marg{end} for each tick interval. -\end{pgfplotsxykey} - -\subsubsection{Comb Plots} -Comb plots are very similar to bar plots except that they employ single horizontal/vertical lines instead of rectangles. - -\begin{plottype}{xcomb} -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot+[xcomb] coordinates - {(4,0) (1,1) (2,2) - (5,3) (6,4) (1,5)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{plottype} - -\begin{plottype}{ycomb} -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot+[ycomb] plot coordinates - {(0,3) (1,2) (2,4) (3,1) (4,2)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{plottype} - -\subsubsection{Stacked Plots} -\begin{pgfplotskey}{stack plots=\mchoice{x,y,false} (initially false)} - Allows stacking of plots in either $x$ or $y$ direction. Stacking means to add either $x$- or $y$ coordinates of successive |\addplot| commands on top of each other. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[stack plots=y] - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)}; - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)}; - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -|stack plots| is particularly useful for bar plots. The following examples demonstrate its functionality. Normally, it is advisable to use the styles |ybar stacked| and |xbar stacked| which also set some other options. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[stack plots=y,/tikz/ybar] - \addplot coordinates - {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; - \addplot coordinates - {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; - \addplot coordinates - {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ybar stacked] - \addplot coordinates - {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; - \addplot coordinates - {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; - \addplot coordinates - {(0,1) (1,1) (2,3) (3,2) (4,1.5)}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[stack plots=x,/tikz/xbar] - \addplot coordinates - {(1,0) (2,1) (2,2) (3,3)}; - \addplot coordinates - {(1,0) (2,1) (2,2) (3,3)}; - \addplot coordinates - {(1,0) (2,1) (2,2) (3,3)}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\begin{codeexample}[] - -\begin{tikzpicture} - \begin{axis}[xbar stacked] - \addplot coordinates - {(1,0) (2,1) (2,2) (3,3)}; - \addplot coordinates - {(1,0) (2,1) (2,2) (3,3)}; - \addplot coordinates - {(1,0) (2,1) (2,2) (3,3)}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -The current implementation for |stack plots| does \emph{not} interpolate missing coordinates. That means stacking will fail if the plots have different grids. -\end{pgfplotskey} - -\begin{pgfplotskey}{stack dir=\mchoice{plus,minus} (initially plus)} - Configures the direction of |stack plots|. The value |plus| will add coordinates of successive plots while |minus| subtracts them. -\end{pgfplotskey} - -\begin{pgfplotskey}{reverse stacked plots=\mchoice{true,false} (initially true, default true)} - Configures the sequence in which stacked plots are drawn. This is more or less a technical detail which should not be changed in any normal case. - - The motivation is as follows: suppose multiple |\addplot| commands are stacked on top of each other and they are processed in the order of appearance. Than, the second plot could easily draw its lines (or fill area) on top of the first one - hiding its marker or line completely. Therefor, \PGFPlots\ reverses the sequence of drawing commands. - - This has the side-effect that any normal \Tikz-paths inside of an axis will also be processed in reverse sequence. -\end{pgfplotskey} - -\begin{stylekey}{/pgfplots/xbar stacked=\mchoice{plus,minus} (default plus)} - A figure-wide style which enables stacked horizontal bars (i.e. |xbar| and |stack plots=x|). It also adjusts the legend and tick appearance and assigns a useful |cycle list|. -\end{stylekey} -\begin{stylekey}{/pgfplots/ybar stacked=\mchoice{plus,minus} (default plus)} - A figure-wide style which enables stacked vertical bars (i.e. |ybar| and |stack plots=y|). It also adjusts the legend and tick appearance and assigns a useful |cycle list|. -\end{stylekey} - -\begin{stylekey}{/pgfplots/xbar interval stacked=\mchoice{plus,minus} (default plus)} - A style similar to |/pgfplots/xbar stacked| for the interval based bar plot variant. -\end{stylekey} -\begin{stylekey}{/pgfplots/ybar interval stacked=\mchoice{plus,minus} (default plus)} - A style similar to |/pgfplots/ybar stacked| for the interval based bar plot variant. -\end{stylekey} - -\subsubsection{Area Plots} -Area plots are a combination of |\closedcycle| and |stack plots|. They can be combined with any other plot type. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - stack plots=y, - area style, - enlarge x limits=false] - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)} - \closedcycle; - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)} - \closedcycle; - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)} - \closedcycle; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\noindent -Area plots may need modified legends, for example using the |area legend| key. Furthermore, one may want to consider the |axis on top| key such that filled areas do not overlap ticks and grid lines. - -\begin{stylekey}{/pgfplots/area style} - A style which sets -\begin{codeexample}[code only] -\pgfplotsset{ - /pgfplots/area style/.style={% - area cycle list, - area legend, - axis on top, - }} -\end{codeexample} -\end{stylekey} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - const plot, - stack plots=y, - area style, - enlarge x limits=false] - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)} - \closedcycle; - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)} - \closedcycle; - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)} - \closedcycle; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - smooth, - stack plots=y, - area style, - enlarge x limits=false] - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)} - \closedcycle; - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)} - \closedcycle; - \addplot coordinates - {(0,1) (1,1) (2,2) (3,2)} - \closedcycle; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\pgfplotstableread{pgfplots.timeseries.dat}\table -\pgfplotstabletypeset\table -\end{codeexample} -\begin{codeexample}[] -\pgfplotstableread - {pgfplots.timeseries.dat} - {\table} - -\begin{tikzpicture} - \begin{axis}[ - ymin=0, - minor tick num=4, - enlarge x limits=false, - axis on top, - every axis plot post/.append style= - {mark=none}, - const plot, - legend style={ - area legend, - at={(0.5,-0.15)}, - anchor=north, - legend columns=-1}] - - \addplot[draw=blue,fill=blue!30!white] - table[x=time,y=1minload] from \table - \closedcycle; - \addplot table[x=time,y=nodes] from \table; - \addplot table[x=time,y=cpus] from \table; - \addplot table[x=time,y=processes] - from \table; - \legend{1min load,nodes,cpus,processes} - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[width=4cm] -\pgfplotstableread{pgfplots.timeseries.dat}\table - -\begin{tikzpicture} - \begin{axis}[ - ymin=0, - minor tick num=4, - enlarge x limits=false, - const plot, - axis on top, - stack plots=y, - cycle list={% - {blue!70!black,fill=blue},% - {blue!60!white,fill=blue!30!white},% - {draw=none,fill={rgb:red,138;green,82;blue,232}},% - {red,thick}% - }, - ylabel={Mem [GB]}, - legend style={ - area legend, - at={(0.5,-0.15)}, - anchor=north, - legend columns=2}] - - \addplot table[x=time,y=memused] from \table \closedcycle; - \addplot table[x=time,y=memcached] from \table \closedcycle; - \addplot table[x=time,y=membuf] from \table \closedcycle; - \addplot plot[stack plots=false] - table[x=time,y=memtotal] from \table; - \legend{Memory used,Memory cached,Memory buffered,Total memory} - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\subsubsection{Scatter Plots} -The most simple scatter plots produce the same as the line plots above -- but they contain only markers. They are enabled using the |only marks| key of \Tikz. -\begin{plottype}{only marks} -Draws a simple scatter plot: all markers have the same appearance. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[enlargelimits=false] - \addplot+[only marks] - expression[samples=400] - {rand}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - The |only marks| visualization style simply draws marks at every coordinate. Marks can be set with |mark=|\meta{mark name} and marker options like size and color can be specified using the |mark options=|\marg{style options} key (or by modifying the |every mark| style). The available markers along with the accepted style options can be found in section~\ref{sec:markers} on page~\pageref{sec:markers}. -\end{plottype} - -\label{pgfplots:scatter} -More sophisticated scatter plots change the marker appearance for each data point. An example is that marker colors depend on the magnitude of function values $f(x)$ or other provided coordinates. The term ``scatter plot'' will be used for this type of plots in the following sections. - -Scatter plots require ``source'' coordinates. These source coordinates can be the $y$ coordinate, or explicitly provided additional values. - -\begin{plottype}{scatter} - Enables marker appearance modifications. The default implementation acquires ``source coordinates'' for every data point (see |scatter src| below) and maps them linearly into the current color map. The resulting color is used as draw and fill color of the marker. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis} - \addplot+[scatter,only marks] - expression[samples=50,scatter src=y] - {x-x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - - The key |scatter| is simply a boolean variable which enables marker modifications. It applies only to markers and it can be combined with any other plot type. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis} - \addplot+[scatter] - expression[samples=50,scatter src=y] - {x^3}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\end{plottype} - -Scatter plots can be configured using a set of options. One of them is mandatory, the rest allows fine grained control over marker appearance options. - -\label{pgfplots:scatter:src} -\begin{pgfplotskey}{scatter src=\mchoice{none,x,y,z,explicit,explicit symbolic} (initially none)} - This key is necessary for any scatter plot. It needs to be provided as \marg{behavior option} for |\addplot| to configure the value used to determine marker appearances. - - Usually, |scatter src| provides input data (numeric or string type) which is used to determine colors and other style options for markers. - The default configuration expects numerical data which is mapped linearly into the current color map. - - The choices |x|, |y| and |z| will use either the $x$, $y$ or $z$ coordinates to determine marker options\footnote{The coordinates are used after any coordinate filters, logarithms or stacked-plot computations have been applied.}. The choice |explicit| expects the scatter source data as additional coordinate from the coordinate input streams (see section~\ref{pgfplots:providing:input} for how to provide input meta data or below for some small examples). They will be treated as numerical data. Finally, |explicit symbolic| also expects scatter source data as additional meta information for each input coordinate, but it treats them as strings, not as numerical data. Consequently, no arithmetics is performed. It is task of the scatter plot style to do sometthing with it. See, for example, the |scatter/classes| style below. - - Here are examples for how to provide data for the choices |explicit| and |explicit symbolic|. -\begin{codeexample}[code only] -\begin{tikzpicture} - \begin{axis} - % provide color data explicitly using [<data>] - % behind coordinates: - \addplot+[scatter] - [scatter src=explicit] - coordinates { - (0,0) [1.0e10] - (1,2) [1.1e10] - (2,3) [1.2e10] - (3,4) [1.3e10] - % ... - }; - - % Assumes a datafile.dat like - % xcolname ycolname colordata - % 0 0 0.001 - % 1 2 0.3 - % 2 2.1 0.4 - % 3 3 0.5 - % ... - % the file may have more columns. - \addplot+[scatter] - [scatter src=explicit] - table[x=xcolname,y=ycolname,meta=colordata] - {datafile.dat}; - - % Assumes a datafile.dat like - % 0 0 0.001 - % 1 2 0.3 - % 2 2.1 0.4 - % 3 3 0.5 - % ... - % the first three columns will be used here: - \addplot+[scatter] - [scatter src=explicit] - file {datafile.dat}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - - Please note that |scatter src|$\neq$|none| results in computational work even if |scatter=false|. -\end{pgfplotskey} - -\begin{stylekey}{/pgfplots/scatter/use mapped color=\marg{options for each marker} (initially draw=mapped color!80!black,fill=mapped color)} - This style is installed by default. When active, it recomputes the color |mapped color| for every processed point coordinate by transforming the |scatter src| coordinates into the current colormap linearly. Then, it evaluates the options provided as \marg{options for each marker} which are expected to depend on |mapped color|. - - The user interface for colormaps is described in section~\ref{pgfplots:colormap}. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[title=Default arguments] -\addplot+[scatter] - expression[scatter src=y] - {2*x+3}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - title=Black fill color and varying draw color, - scatter/use mapped color= - {draw=mapped color,fill=black}] -\addplot+[scatter] - expression[scatter src=y] - {2*x+3}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - title=Black draw color and varying fill color, - scatter/use mapped color= - {draw=black,fill=mapped color}] -\addplot+[scatter] - expression[scatter src=y] - {2*x+3}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - This key is actually a style which redefines |@pre marker code| and |@post marker code| (see below). -\end{stylekey} - -\label{pgfplots:scatterclasses} -\begin{stylekey}{/pgfplots/scatter/classes=\marg{styles for each classname}} - A scatter plot style which visualizes points using several classes. The style assumes that every point coordinate has a class label attached, that means the choice |scatter src=explicit symbolic| is assumed\footnote{If \texttt{scatter src} is not \texttt{explicit symbolic}, we expect a numeric argument which is rounded to the nearest integer. The resulting integer is used a class label. If that fails, the numeric argument is truncated to the nearest integer. If that fails as well, the point has no label.}. A class label can be a number, but it can also be a symbolic constant. Given class labels for every point, \marg{styles for each classname} contains a comma-separated list which associates appearance options to each class label. - - If you need different |scatter/classes| arguments per plot, they must be given as \marg{behavior option}, not as style option. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[scatter/classes={ - a={mark=square*,blue},% - b={mark=triangle*,red},% - c={mark=o,draw=black}}] - - % \addplot[] is better than \addplot+[] here: - % it avoids scalings of the cycle list - \addplot[scatter,only marks] - plot[scatter src=explicit symbolic] - coordinates { - (0.1,0.15) [a] - (0.45,0.27) [c] - (0.02,0.17) [a] - (0.06,0.1) [a] - (0.9,0.5) [b] - (0.5,0.3) [c] - (0.85,0.52) [b] - (0.12,0.05) [a] - (0.73,0.45) [b] - (0.53,0.25) [c] - (0.76,0.5) [b] - (0.55,0.32) [c] - }; -\end{axis} -\end{tikzpicture} -\end{codeexample} -In this example, the coordinate |(0.1,0.15)| has the associated label `|a|' while |(0.45,0.27)| has the label `|c|' (see section~\ref{sec:addplot} for details about specifying point meta data). Now, The argument to |scatter/classes| contains styles for every label -- for label `|a|', square markers will be drawn in color blue. - -\begin{codeexample}[code only] -\begin{tikzpicture} -\begin{axis}[scatter/classes={ - 0={mark=square*,blue},% - 1={mark=triangle*,red},% - 2={mark=o,draw=black,fill=black}}] - - % Assumes datafile.dat looks like - % x y label - % 5.000000e-01 7.500000e-01 1 - % 1.000000e+00 6.718750e-01 2 - % 1.000000e+00 5.597630e-01 2 - % 5.000000e-01 1.250000e-01 2 - % 1.000000e+00 6.603350e-01 0 - % 5.000000e-01 0.000000e+00 0 - % 0.000000e+00 5.000000e-01 0 - % 1.000000e+00 0.000000e+00 2 - % 5.000000e-01 1.250000e-01 1 - % 1.000000e+00 6.213180e-01 1 - % ... - \addplot[scatter,only marks] - table[scatter src=explicit symbolic,x index=x,y index=y,meta=label] - {datafile.dat} - ; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -In general, the format of \marg{styles for each classname} is a comma separated list of \meta{label}|=|\marg{style options}. - -\paragraph{Attention:} The keys |every mark| and |mark options| have \emph{no effect} when used inside of \marg{styles for each classname}! So, instead of assigning |mark options|, you can simply provide the options directly. They apply only to markers anyway. -\end{stylekey} - -\begin{pgfplotsxycodekeylist}{ - scatter/@pre marker code, - scatter/@post marker code} - These two keys constitute the public low-level interface which determines the marker appearance depending on the scatter source coordinates. - - Redefining them allows fine grained control even over marker types, linestyles and colors. - - The scatter plot algorithm works as follows: -\begin{enumerate} -\item The scatter source coordinates form a data stream whose data limits are computed additionally to the axis limits. This step is skipped for |symbolic| meta data. -\item Before any markers are drawn, a linear coordinate transformation from these data limits to the interval $[0.0,1000.0]$ is initialised. -\item Every scatter source coordinate\footnote{During the evaluation, the public macros \texttt{\textbackslash pgfplotspointmeta} and \texttt{\textbackslash pgfplotspointmetarange} indicate the source coordinate and the source coordinate range in the format $a:b$ (for log--axis, they are given in fixed point representation and for linear axes in floating point).} will be transformed linearly and the result is available as macro |\pgfplotspointmetatransformed| $ \in [0.0,1000.0]$. - -The decision is thus based on per thousands of the data range. The transformation is skipped for |symbolic| meta data (and the meta data is simply contained in the mentioned macro). -\item The code of |scatter/@pre marker code| is evaluated (without arguments). -\item The standard code which draws markers is evaluated. -\item The code of |scatter/@post marker code| is evaluated (without arguments). -\end{enumerate} - The idea is to generate a set of appearance keys which depends on |\pgfplotspointmetatransformed|. Then, a call to |\scope|\oarg{generated keys} as |@pre| code and the associated |\endscope| as |@post| code will draw markers individually using \oarg{generated keys}. - -A technical example is shown below. It demonstrates how to write user defined routines, in this case a three--class system\footnote{Please note that you don't need to copy this particular example: the multiple--class example is also available as predefined style \texttt{scatter/classes}.}. -\begin{codeexample}[] -\begin{tikzpicture} -% Low-Level scatter plot interface Example: -% use three different marker classes -% 0% - 30% : first class -% 30% - 60% : second class -% 60% - 100% : third class -\begin{axis}[ -scatter/@pre marker code/.code={% - \ifdim\pgfplotspointmetatransformed pt<300pt - \def\markopts{mark=square*,fill=blue}% - \else - \ifdim\pgfplotspointmetatransformed pt<600pt - \def\markopts{mark=triangle*,fill=orange}% - \else - \def\markopts{mark=pentagon*,fill=red}% - \fi - \fi - \expandafter\scope\expandafter[\markopts] -},% -scatter/@post marker code/.code={% - \endscope -}] - -\addplot+[scatter] - expression[scatter src=y,samples=40] - {sin(deg(x))}; - -\end{axis} -\end{tikzpicture} -\end{codeexample} -Please note that |\ifdim| compares \TeX\ lengths, so the example employs the suffix |pt| for any number used in this context. That doesn't change the semantics. - -\end{pgfplotsxycodekeylist} - -\subsubsection{Interrupted Plots} -\index{Interrupted Plots}% -Sometimes it is desireable to draw parts of a single plot separately, without connection between the parts (discontinuities). There is limited support for such an application. -\label{pgfplots:interrupt} -\begin{pgfplotskey}{/pgfplots/forget plot=\marg{true,false} (initially false)} - This key tells \PGFPlots\ to add a plot without changing cycle list position and legends. This key is described in all detail on page~\pageref{pgfplots:forgetplot}. - - However, it can be used to get the interesting effect of ``interrupted plot'', so it is also discussed here: -\begin{codeexample}[width=4cm] -\begin{tikzpicture} -\begin{axis}[ - width=10cm, height=210pt, - xmin=-4.7124, xmax=4.7124, - ymin=-10, ymax=10, - xtick={-4.7124,-1.5708,...,10}, - xticklabels={$-\frac32 \pi$,$-\pi/2$,$\pi/2$,$\frac32 \pi$}, - axis x line=center,axis y line=center, - no markers, - samples=100] - -% Use gnuplot as calculator here. The first two plots won't be counted: -\addplot gnuplot[id=tan0,forget plot,domain=-1.5*pi+0.003:-0.5*pi-0.003] {tan(x)}; -\addplot gnuplot[id=tan1,forget plot,domain=-0.5*pi+0.003: 0.5*pi-0.003] {tan(x)}; -\addplot gnuplot[id=tan2, domain= 0.5*pi+0.003: 1.5*pi-0.003] {tan(x)}; -\legend{$\tan(x)$} -\end{axis} -\end{tikzpicture} -\end{codeexample} - - The interesting part is in the |\addplot| commands. The |id| is specific to the gnuplot interface (and can be omitted). The |domain| option defines separate domains for every plot part. Due to the |forget plot| key, the |cycle list| position is not updated so all three plots use the same line specification. Furthermore, only the last command affects the legend (and advances the cycle list). - - \paragraph{Remark:} The |forget plot| feature is \emph{not very sophisticated}. In particular, it has the following \textbf{restrictions}: - \begin{enumerate} - \item Besides the |cycle list| side--effect, no styles are communicated between successive plots. - \item It won't work together with |stack plots|. - \end{enumerate} -\end{pgfplotskey} - -\subsection{Markers and Linestyles} -\label{sec:markers}% -The following options of \Tikz\ are available to plots. -\subsubsection{Markers} -This list is copied from~\cite[section~29]{tikz}: -\begingroup -\newenvironment{longdescription}[0]{% - \begin{list}{}{% - \leftmargin=4.3cm - \setlength{\labelwidth}{4.3cm}% - \renewcommand{\makelabel}[1]{\hfill\textbf{\texttt{##1}}}% - }% -}{% - \end{list}% -}% -\def\showit#1{% - \tikz\draw[% - gray, - thin, - mark options={fill=yellow!80!black,draw=black,scale=2}, - x=0.8cm,y=0.3cm, - #1] - plot coordinates {(0,0) (1,1) (2,0) (3,1)};% -}% -\begin{longdescription} - \item[mark=*] \showit{mark=*} - \item[mark=x] \showit{mark=x} - \item[mark=+] \showit{mark=+} -% \item[mark=ball] \showit{mark=ball} -\end{longdescription} -And with |\usetikzlibrary{plotmarks}|: -\begin{longdescription} - \item[mark=$-$] \showit{mark=-} - \item[mark=$\vert$] \showit{mark=|} - \item[mark=o] \showit{mark=o} - \item[mark=asterisk] \showit{mark=asterisk} - \item[mark=star] \showit{mark=star} - \item[mark=oplus] \showit{mark=oplus} - \item[mark=oplus*] \showit{mark=oplus*} - \item[mark=otimes] \showit{mark=otimes} - \item[mark=otimes*] \showit{mark=otimes*} - \item[mark=square] \showit{mark=square} - \item[mark=square*] \showit{mark=square*} - \item[mark=triangle] \showit{mark=triangle} - \item[mark=triangle*] \showit{mark=triangle*} - \item[mark=diamond] \showit{mark=diamond} - \item[mark=diamond*] \showit{mark=diamond*} - \item[mark=pentagon] \showit{mark=pentagon} - \item[mark=pentagon*] \showit{mark=pentagon*} - \item[mark=text] \showit{mark=text,every mark/.append style={scale=0.5}} - - This marker is special as it can be configured freely. The character (or even text) used is configured by a set of variables, see below. -\end{longdescription} -All these options have been drawn with the additional options -\begin{codeexample}[code only] -\draw[ - gray, - thin, - mark options={% - scale=2,fill=yellow!80!black,draw=black - } -] -\end{codeexample} -Please see section~\ref{sec:colors} for how to change draw- and fill colors. - -\begin{key}{/pgf/text mark=\marg{text} (initially p)} - Changes the text shown by |mark=text|. - - With |/pgf/text mark=m|: \pgfkeys{/pgf/text mark=m}\showit{mark=text,every mark/.append style={scale=0.5}} - - With |/pgf/text mark=A|: \pgfkeys{/pgf/text mark=A}\showit{mark=text,every mark/.append style={scale=0.5}} - - There is no limitation about the number of characters or whatever. In fact, any \TeX\ material can be inserted as \marg{text}, including images. -\end{key} -\begin{key}{/pgf/text mark/style=\marg{options for \texttt{mark=text}}} - Defines a set of options which control the appearance of |mark=text|. - - If |/pgf/text mark/as node=false| (the default), \marg{options} is provided as argument to |\pgftext| -- which provides only some basic keys like |left|, |right|, |top|, |bottom|, |base| and |rotate|. - - If |/pgf/text mark/as node=true|, \marg{options} is provided as argument to |\node|. This means you can provide a very powerful set of options including |anchor|, |scale|, |fill|, |draw|, |rounded corners| etc. -\end{key} -\begin{key}{/pgf/text mark/as node=\mchoice{true,false} (initially false)} - Configures how |mark=text| will be drawn: either as |\node| or as |\pgftext|. - - The first choice is highly flexible and possibly slow, the second is very fast and usually enough. -\end{key} - -\begin{key}{/tikz/mark size=\marg{dimension}} - This \Tikz\ option allows to set marker sizes to \marg{dimension}. For circular markers, \marg{dimension} is the radius, for other plot marks it is about half the width and height. -\end{key} -\begin{key}{/tikz/every mark} - This \Tikz\ style can be reconfigured to set marker appearance options like colors or transformations like scaling or rotation. \PGFPlots\ appends its cycle list options to this style. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[y=2cm] - \addplot coordinates - {(-2,0) (-1,1) (0,0) (1,1) (2,0)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\tikzset{every mark/.append style={scale=2}} -\begin{tikzpicture} -\begin{axis}[y=2cm] - \addplot coordinates - {(-2,0) (-1,1) (0,0) (1,1) (2,0)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{key} - -\begin{stylekey}{/pgfplots/every axis plot post (initially {})} -The |every axis plot post| style can be used to overwrite parts (or all) of the drawing styles which are assigned for plots. -\begin{codeexample}[] -% Overwrite any cycle list: -\pgfplotsset{ - every axis plot post/.append style={ - mark=triangle, - every mark/.append style={rotate=90}}} -\begin{tikzpicture} -\begin{axis}[y=2cm] - \addplot coordinates - {(-2,0) (-1,1) (0,0) (1,1) (2,0)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{stylekey} - -\begin{stylekey}{/pgfplots/no markers} - A style which appends |mark=none| to |every axis plot post|, which disables markers for every plot (even if the cycle list contains markers). -\end{stylekey} - -\begin{key}{/tikz/mark options=\marg{options}} - Resets |every mark| to \marg{options}. -\end{key} - -Markers paths are not subjected to clipping as other parts of the figure. Markers are either drawn completely or not at all. - -\Tikz\ offers more options for marker fine tuning, please refer to~\cite{tikz} for details. - -\subsubsection{Line Styles} -\def\showit#1{% - \tikz\draw[% - black, - x=0.8cm,y=0.3cm, - #1] - plot coordinates {(0,0) (1,1) (2,0) (3,1)};% -}% -The following line styles are predefined in \Tikz. -\begin{stylekey}{/tikz/solid} - \showit{style=solid} -\end{stylekey} - -\begin{stylekey}{/tikz/dotted} - \showit{style=dotted} -\end{stylekey} - -\begin{stylekey}{/tikz/densely dotted} - \showit{style=densely dotted} -\end{stylekey} - -\begin{stylekey}{/tikz/loosely dotted} - \showit{style=loosely dotted} -\end{stylekey} - -\begin{stylekey}{/tikz/dashed} - \showit{style=dashed} -\end{stylekey} - -\begin{stylekey}{/tikz/densely dashed} - \showit{style=densely dashed} -\end{stylekey} - -\begin{stylekey}{/tikz/loosely dashed} - \showit{style=loosely dashed} -\end{stylekey} -\noindent since these styles apply to markers as well, you may want to consider using -\begin{codeexample}[code only] -\pgfplotsset{ - every mark/.append style={solid} -} -\end{codeexample} -\noindent in marker styles. - -Besides linestyles, \PGF\ also offers (a lot of) arrow heads. Please refer to~\cite{tikz} for details. -\endgroup - - -\subsubsection{Font Size and Line Width} -Often, one wants to change line width and font sizes for plots. This can be done using the following options of \Tikz. - -\begin{key}{/tikz/font=\marg{font name} (initially \textbackslash normalfont)} - Sets the font which is to be used for text in nodes (like tick labels, legends or descriptions). - - A font can be any \LaTeX\ argument like |\footnotesize| or |\small\bfseries|\footnote{Con\TeX t and plain \TeX\ users need to provide other statements, of course.}. - - It may be useful to change fonts only for specific axis descriptions, for example using -\begin{codeexample}[code only] -\pgfplotsset{ - tick label style={font=\small}, - label style={font=\small}, - legend style={font=\footnotesize} -} -\end{codeexample} -\end{key} - -\begin{key}{/tikz/line width=\marg{dimension} (initially 0.4pt)} - Sets the line width. Please note that line widths for tick lines and grid lines are predefined, so it may be necessary to override the styles |every tick| and |every axis grid|. - - The |line width| key is changed quite often in \Tikz. You should use -\begin{codeexample}[code only] -\pgfplotsset{every axis/.append style={line width=1pt}} -\end{codeexample} - or -\begin{codeexample}[code only] -\pgfplotsset{every axis/.append style={thick}} -\end{codeexample} - to change the overall line width. To also adjust ticks and grid lines, one can use -\begin{codeexample}[code only] -\pgfplotsset{every axis/.append style={ - line width=1pt, - tick style={line width=0.6pt}}} -\end{codeexample} - or styles like -\begin{codeexample}[code only] -\pgfplotsset{every axis/.append style={ - thick, - tick style={semithick}}} -\end{codeexample} - The `|every axis plot|' style can be used to change line widths for plots only. -\end{key} - -\begin{keylist}[/tikz]{ultra thin,very thin,semithick,thick,very thick,ultra thick} - These \Tikz\ styles provide different predefined line widths. -\end{keylist} - -This example shows the same plots as on page~\pageref{page:plotcoords:src} (using |\plotcoords| as place holder for the commands on page~\pageref{page:plotcoords:src}), with different line width and font size. -\begin{codeexample}[] -\pgfplotsset{every axis/.append style={ - font=\large, - line width=1pt, - tick style={line width=0.8pt}}} -\begin{tikzpicture} - \begin{loglogaxis}[ - legend style={at={(0.03,0.03)}, - anchor=south west}, - xlabel=\textsc{Dof}, - ylabel=$L_2$ Error - ] - % see above for this macro: - \plotcoords - \legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} - \end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\pgfplotsset{every axis/.append style={ - font=\footnotesize, - thin, - tick style={ultra thin}}} -\begin{tikzpicture} - \begin{loglogaxis}[ - xlabel=\textsc{Dof}, - ylabel=$L_2$ Error - ] - % see above for this macro: - \plotcoords - \legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} - \end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - -\subsubsection{Colors} -\label{sec:colors} -{% -\def\showcolorandname#1{% - \showcolor{#1}~#1% -}% -\def\showcolor#1{% - \tikz \draw[black,fill={#1}] (0,0) rectangle (1em,0.6em);% -}% -\PGF\ uses the color support of |xcolor|. Therefore, the main reference for how to specify colors is the |xcolor| manual~\cite{xcolor}. The \PGF\ manual~\cite{tikz} is the reference for how to select colors for specific purposes like drawing, filling, shading, patterns etc.\ This section contains a short overview over the specification of colors in~\cite{xcolor} (which is not limited to \PGFPlots). - -The package |xcolor| defines a set of predefined colors, namely -\showcolorandname{red}, -\showcolorandname{green}, -\showcolorandname{blue}, -\showcolorandname{cyan}, -\showcolorandname{magenta}, -\showcolorandname{yellow}, -\showcolorandname{black}, -\showcolorandname{gray}, -\showcolorandname{white}, -\showcolorandname{darkgray}, -\showcolorandname{lightgray}, -\showcolorandname{brown}, -\showcolorandname{lime}, -\showcolorandname{olive}, -\showcolorandname{orange}, -\showcolorandname{pink}, -\showcolorandname{purple}, -\showcolorandname{teal}, -\showcolorandname{violet}. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[enlarge x limits=false] - \addplot[red] - expression[samples=500] {sin(deg(x))}; - - \addplot[orange] - expression[samples=7] {sin(deg(x))}; - - \addplot[teal,const plot] - expression[samples=14] {sin(deg(x))}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -Besides predefined colors, it is possible to \emph{mix} two (or more) colors. For example, \showcolorandname{red!30!white} contains $30\%$ of \showcolorandname{red} and $70\%$ of \showcolorandname{white}. Consequently, one can build \showcolorandname{red!70!white} to get $70\%$ red and $30\%$ white or \showcolorandname{red!10!white} for $10\%$ red and $90\%$ white. This mixing can be done with any color, \showcolorandname{red!50!green}, \showcolorandname{blue!50!yellow}. - -A different type of color mixing is supported, which allows to take $100\%$ of \emph{each} component. For example, \showcolorandname{rgb,2:red,1;green,1} will add $1/2$ part \showcolorandname{red} and $1/2$ part \showcolorandname{green} and we reproduced the example from above. Using the denominator~$1$ instead of~$2$ leads to \showcolorandname{rgb,1:red,1;green,1} which uses $1$ part \showcolorandname{red} and $1$ part \showcolorandname{green}. Many programs allow to select pieces between $0,\dotsc,255$, so a denominator of $255$ is useful. Consequently, \showcolorandname{rgb,255:red,231;green,84;blue,121} uses $231/255$ red, $84/255$ green and $121/255$. This corresponds to the standard RGB color $(231,84,121)$. Other examples are \showcolorandname{rgb,255:red,32;green,127;blue,43}, \showcolorandname{rgb,255:red,178;green,127;blue,43}, \showcolorandname{rgb,255:red,169;green,178;blue,43}. - -It is also possible to use RGB values, the HSV color model or the HTML color syntax directly. However, this requires some more programming. I suppose this is the fastest (and probably the most uncomfortable) method to use colors. For example, -\begin{codeexample}[] -\definecolor{color1}{rgb}{1,1,0} -\tikz \fill[color1] - (0,0) rectangle (1em,0.6em); -\end{codeexample} -\noindent creates the color with $100\%$ red, $100\%$ green and $0\%$ blue; - -\begin{codeexample}[] -\definecolor{color1}{HTML}{D0B22B} -\tikz \fill[color1] - (0,0) rectangle (1em,0.6em); -\end{codeexample} -\noindent creates the color with $208/255$ pieces red, $178/255$ pieces green and $43$ pieces blue, specified in standard HTML notation. Please refer to the |xcolor| manual~\cite{xcolor} for more details and color models. -}% - -\begin{keylist}{ - /tikz/color=\marg{a color}, - /tikz/draw=\marg{stroke color}, - /tikz/fill=\marg{fill color}} - These keys are (generally) used to set colors. Use |color| to set the color for both, drawing and filling. Instead of |color=|\marg{color name} you can simply write \marg{color name}. The |draw| and |fill| keys only set colors for stroking and filling, respectively. - - Use |draw=none| to disable drawing and |fill=none| to disable filling\footnote{Up to now, plot marks always have a stroke color (some also have a fill color). This restriction may be lifted in upcoming versions.}.% This does also work for markers. -%-------------------------------------------------- -% \begin{codeexample}[] -% \begin{tikzpicture} -% \begin{axis} -% \addplot+[only marks,mark=square*, -% mark options={fill=red!50!white,draw=none}] -% {4*x^2 - 2*x +4 }; -% \end{axis} -% \end{tikzpicture} -% \end{codeexample} -%-------------------------------------------------- - - Since these keys belong to \Tikz, the complete documentation can be found in the \Tikz\ manual~\cite[Section ``Specifying a Color'']{tikz}. -\end{keylist} - -\subsubsection{Color Maps} -\label{pgfplots:colormap} -\begin{pgfplotskey}{colormap name=\marg{color map name} (initially hot)} - Changes the current color map to the already defined map named \marg{color map name}. The predefined color map is - - \begin{tabular}{>{\ttfamily}ll} - hot & \pgfplotsshowcolormap{hot}\\ - \end{tabular} - - Further colormaps are described below. - - Colormaps can be used, for example, in scatter plots (see section~\ref{pgfplots:scatter}). - - You can use |colormap| to create new color maps (see below). -\end{pgfplotskey} - -\begin{pgfplotskey}{colormap=\marg{name}\marg{color specification}} - Defines a new colormap named \marg{name} according to \marg{color specification} and activates it using |colormap name=|\marg{name}. - - The syntax of \marg{color specification} is the same as those for \PGF\ shadings described in~\cite[VIII -- Shadings]{tikz}: it consists of a series of colors along with a length. -\begin{codeexample}[code only] -rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb255(2cm)=(0,0,255); gray(3cm)=(0.3); color(4cm)=(green) -\end{codeexample} -\pgfplotsshowcolormapexample{rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb255(2cm)=(0,0,255); gray(3cm)=(0.3); color(4cm)=(green)} - -\noindent The single colors are separated by semicolons `|;|'. The length describes how much of the bar is occupied by the interval. Each entry has the form \meta{color model}|(|\meta{length}|)=(|\meta{arguments}|)|. The line above means that the left end of the colormap shall have RGB components $1,0,0$, indicating $100\%$ red and $0\%$ green and blue. The next entity starts at |1cm| and describes a color with $100\%$ green. The |rgb255| also expects three RGB components, but in the range $[0,255]$. Finally, |gray| specifies a color in parenthesis with the same value for each, R G and B and |color| accesses predefined colors. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - colormap={bw}{gray(0cm)=(0); gray(1cm)=(1)}] - \addplot+[scatter,only marks] - plot[scatter src=y,domain=0:8,samples=100] - {exp(x)}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -The complete length of a colormap is irrelevant: it will be mapped linearly to an internal range anyway (for efficient interpolation). The only requirement is that the left end must be at |0|. - -Available colormaps are shows below. - -\paragraph{Remark:} Currently, only equidistant \marg{color specification}s are supported (each interval must have the same length). -\end{pgfplotskey} - -\begin{stylekey}{/pgfplots/colormap/hot} - A style which installs the colormap - - |{color(0cm)=(blue); color(1cm)=(yellow); color(2cm)=(orange); color(3cm)=(red)}| - - \pgfplotsshowcolormap{hot} - - This is the preconfigured colormap. -\end{stylekey} - -\begin{stylekey}{/pgfplots/colormap/bluered} - A style which installs the colormap - - |{rgb255(0cm)=(0,0,180); rgb255(1cm)=(0,255,255); rgb255(2cm)=(100,255,0); | - - |rgb255(3cm)=(255,255,0); rgb255(4cm)=(255,0,0); rgb255(5cm)=(128,0,0)}|, - - \pgfplotsshowcolormap{bluered} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[colormap/bluered] - \addplot+[scatter] - expression[scatter src=x,samples=50] - {sin(deg(x))}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - - \paragraph{Remark:} - The style |bluered| (re-)defines the colormap and activates it. \TeX\ will be slightly faster if you call |\pgfplotsset{colormap/bluered}| in the preamble (to create the colormap once) and use |colormap name=bluered| whenever you need it. This remark holds for every colormap style which follows. But you can simply ignore this remark. -\end{stylekey} - -\begin{stylekey}{/pgfplots/colormap/cool} - A style which installs the colormap - - |{rgb255(0cm)=(255,255,255); rgb255(1cm)=(0,128,255); rgb255(2cm)=(255,0,255)}| - - \pgfplotsshowcolormap{cool} -\end{stylekey} - -\begin{stylekey}{/pgfplots/colormap/greenyellow} - A style which installs the colormap - - |{rgb255(0cm)=(0,128,0); rgb255(1cm)=(255,255,0)}| - - \pgfplotsshowcolormap{greenyellow} -\end{stylekey} - -\begin{stylekey}{/pgfplots/colormap/redyellow} - A style which installs the colormap - - |{rgb255(0cm)=(255,0,0); rgb255(1cm)=(255,255,0)}| - - \pgfplotsshowcolormap{redyellow} -\end{stylekey} - -\begin{stylekey}{/pgfplots/colormap/blackwhite} - A style which installs the colormap - - |{gray(0cm)=(0); gray(1cm)=(1)}| - - \pgfplotsshowcolormap{blackwhite} -\end{stylekey} - -\begin{command}{\pgfplotscolormaptoshadingspec\marg{colormap name}\marg{right end size}\marg{\textbackslash macro}} - A command which converts a colormap into a \PGF\ shading's color specification. It can be used in commands like |\pgfdeclare*shading| (see the \PGF\ manual~\cite{tikz} for details). - - The first argument is the name of a (defined) colormap, the second the rightmost dimension of the specification. The result will be stored in \meta{\textbackslash macro}. -\begin{codeexample}[] - % convert `hot' -> \result - \pgfplotscolormaptoshadingspec{hot}{8cm}\result - % define and use a shading in pgf: - \def\tempb{\pgfdeclarehorizontalshading{tempshading}{1cm}}% - % where `\result' is inserted as last argument: - \expandafter\tempb\expandafter{\result}% - \pgfuseshading{tempshading}% -\end{codeexample} -The usage of the result \meta{\textbackslash macro} is a little bit low--level. -\end{command} - -\subsubsection{Options Controlling Linestyles} - -\label{sec:cycle:list}% -\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. - -There are several possiblities to change it: -\begin{enumerate} - \item Use one of the predefined lists\footnote{These lists were named \texttt{\textbackslash coloredplotspeclist} and \texttt{\textbackslash blackwhiteplotspeclist} which appeared to be unnecessarily long, so they have been renamed. The old names are still accepted, however.}, - \begin{itemize} - \item |color| (from top to bottom) -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - stack plots=y,stack dir=minus, - cycle list name=color] -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - - \item |exotic| (from top to bottom) -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - stack plots=y,stack dir=minus, - cycle list name=exotic] -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - - \item |black white| (from top to bottom) -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - stack plots=y,stack dir=minus, - cycle list name=black white] -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\addplot coordinates {(0,1) (0.5,1) (1,1)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - \end{itemize} - -These predefined cycle lists habe been created with -\begin{codeexample}[code only] -\pgfplotscreateplotcyclelist{color}{% - blue,every mark/.append style={fill=blue!80!black},mark=*\\% - red,every mark/.append style={fill=red!80!black},mark=square*\\% - brown!60!black,every mark/.append style={fill=brown!80!black},mark=otimes*\\% - black,mark=star\\% - blue,every mark/.append style={fill=blue!80!black},mark=diamond*\\% - red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\% - brown!60!black,densely dashed,every mark/.append style={ - solid,fill=brown!80!black},mark=square*\\% - black,densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\% - blue,densely dashed,mark=star,every mark/.append style=solid\\% - red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\% -} -\pgfplotscreateplotcyclelist{black white}{% - every mark/.append style={fill=gray},mark=*\\% - every mark/.append style={fill=gray},mark=square*\\% - every mark/.append style={fill=gray},mark=otimes*\\% - mark=star\\% - every mark/.append style={fill=gray},mark=diamond*\\% - densely dashed,every mark/.append style={solid,fill=gray},mark=*\\% - densely dashed,every mark/.append style={solid,fill=gray},mark=square*\\% - densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\% - densely dashed,every mark/.append style={solid},mark=star\\% - densely dashed,every mark/.append style={solid,fill=gray},mark=diamond*\\% -} -\pgfplotscreateplotcyclelist{exotic}{% - teal,every mark/.append style={fill=teal!80!black},mark=*\\% - orange,every mark/.append style={fill=orange!80!black},mark=square*\\% - cyan!60!black,every mark/.append style={fill=cyan!80!black},mark=otimes*\\% - red!70!white,mark=star\\% - lime!80!black,every mark/.append style={fill=lime},mark=diamond*\\% - red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\% - yellow!60!black,densely dashed, - every mark/.append style={solid,fill=yellow!80!black},mark=square*\\% - black,every mark/.append style={solid,fill=gray},mark=otimes*\\% - blue,densely dashed,mark=star,every mark/.append style=solid\\% - red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\% -} -\end{codeexample} - - \item Provide the list explicitly, -\begin{codeexample}[] -\begin{tikzpicture} -\begin{loglogaxis}[cycle list={% - {blue,mark=*}, - {red,mark=square}, - {dashed,mark=o}, - {loosely dotted,mark=+}, - {brown!60!black, - mark options={fill=brown!40}, - mark=otimes*}} -] -\plotcoords -\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} -\end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - (This example list requires |\usetikzlibrary{plotmarks}|). - \item Define macro names and use them with `|cycle list name|': -\begin{codeexample}[code only] -\pgfplotscreateplotcyclelist{mylist}{% - {blue,mark=*}, - {red,mark=square}, - {dashed,mark=o}, - {loosely dotted,mark=+}, - {brown!60!black,mark options={fill=brown!40},mark=otimes*}} -... -\begin{axis}[cycle list name=mylist] - ... -\end{axis} -\end{codeexample} -\end{enumerate} - -\paragraph{Remark:} You can also terminate single entries with `|\\|' as in -\begin{codeexample}[code only] -\begin{axis}[cycle list={% - blue,mark=*\\% - red,mark=square\\% - dashed,mark=o\\% - loosely dotted,mark=+\\% - brown!60!black, - mark options={fill=brown!40}, - mark=otimes*\\} -] -... -\end{axis} -\end{codeexample} -In this case, the \emph{last} entry also needs a terminating `|\\|', but one can omit braces around the single entries. -\end{pgfplotskeylist} - - - - -\subsection{Axis Descriptions} -Axis descriptions are labels for $x$ and $y$ axis and titles. Axis descriptions are drawn after the plot is finished and they are not subjected to clipping. Their placement is always \emph{relative to the axis rectangle}, where $(0,0)$ refers to the lower left corner and $(1,1)$ refers to the upper right one. - -Furthermore, axis descriptions can be placed using the predefined node |current axis|. At the time when axis descriptions are drawn, all anchors which refer to the axis origin (that means the ``real'' point $(0,0)$) or any of the axis corners can be references using |current axis.|\meta{anchor name}. Please see section~\ref{pgfplots:sec:align}, Alignment, for further details. - -\subsubsection{Labels} - -\begin{pgfplotsxykey}{\x label=\marg{text}} -The options |xlabel| and |ylabel| change axis labels to \marg{text} which is any \TeX\ text. Use ``|xlabel={, = characters}|'' if characters like `|=|' or `|,|' need to be included literally. - -Labels are \Tikz-Nodes which are placed with -\begin{codeexample}[code only] -\node - [style=every axis label, - style=every axis x label] -\node - [style=every axis label, - style=every axis y label] -\end{codeexample} -so their position and appearance can be customized. The coordinate |(0,0)| denotes the lower left axis corner and |(1,1)| the upper right. - -The default styles are -\begin{codeexample}[code only] -\pgfplotsset{every axis label/.style={}} -\pgfplotsset{every axis x label/.style={ - at={(0.5,0)}, - below, - yshift=-15pt}} -\pgfplotsset{every axis y label/.style={ - at={(0,0.5)}, - xshift=-35pt, - rotate=90}} -\end{codeexample} -Whenever possible, consider using |.append style| instead of overwriting the default styles to ensure compatibility with future versions. -\begin{codeexample}[code only] -\pgfplotsset{every axis label/.append style={...}} -\pgfplotsset{every axis x label/.append style={...}} -\pgfplotsset{every axis y label/.append style={...}} -\end{codeexample} - Use |xlabel/.add=|\marg{prefix}\marg{suffix} to modify an already assigned label. -\end{pgfplotsxykey} - -\begin{pgfplotskey}{title=\marg{text}} -Adds a caption to the plot. This will place a \Tikz-Node with -\begin{codeexample}[code only] -\node[style=every axis title] {text}; -\end{codeexample} -to the current axis. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{loglogaxis}[ - xlabel=Dof,ylabel=Error, - title={$\mu=0.1$, $\sigma=0.2$}] - - \addplot coordinates { - (5, 8.312e-02) - (17, 2.547e-02) - (49, 7.407e-03) - (129, 2.102e-03) - (321, 5.874e-04) - (769, 1.623e-04) - (1793, 4.442e-05) - (4097, 1.207e-05) - (9217, 3.261e-06) - }; -\end{loglogaxis} -\end{tikzpicture}% -\end{codeexample} -%-------------------------------------------------- -% \hfill -% \begin{tikzpicture} -% \begin{loglogaxis}[ -% width=0.48\linewidth, -% xlabel=Dof,ylabel=Error, -% title={$\mu=1$, $\sigma=\frac{1}{2}$}] -% -% \addplot[color=red,mark=*] coordinates { -% (7, 8.472e-02) -% (31, 3.044e-02) -% (111, 1.022e-02) -% (351, 3.303e-03) -% (1023, 1.039e-03) -% (2815, 3.196e-04) -% (7423, 9.658e-05) -% (18943, 2.873e-05) -% (47103, 8.437e-06) -% }; -% \end{loglogaxis} -% \end{tikzpicture} -%-------------------------------------------------- -The title's appearance and/or placing can be reconfigured with -\begin{codeexample}[code only] -\pgfplotsset{every axis title/.append style={at={(0.75,1)}}} -\end{codeexample} -This will place the title at~75\% of the $x$-axis. The coordinate~$(0,0)$ is the lower left corner and~$(1,1)$ the upper right one. - -Use |title/.add=|\marg{prefix}\marg{suffix} to modify an already assigned title. -\end{pgfplotskey} - -\begin{pgfplotscodekey}{extra description} -Allows to insert \marg{commands} after axis labels, titles and legends have been typeset. - -As all other axis descriptions, the code can use $(0,0)$ to access the lower left corner and $(1,1)$ to access the upper right one. It won't be clipped. -\begin{codeexample}[] -\pgfplotsset{every axis/.append style={ - extra description/.code={ - \node at (0.5,0.5) {Center!}; - }}} -\begin{tikzpicture} - \begin{axis} - \addplot {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotscodekey} - - -\subsubsection{Legend} -\label{pgfplots:sec:legendopts} -Legends can be generated in two ways: the first is to use |\addlegendentry| or |\legend| inside of an axis. This method has been presented in section~\ref{pgfplots:sec:legendcmds}, Legend Commands. The other method is to use a key. - -\begin{pgfplotskey}{legend entries=\marg{comma separated list}} - This key can be used to assign legend entries just like the commands |\addlegendentry| and |\legend|. Again, the positioning is relative to the axis rectangle (unless units like |cm| or |pt| are specified explicitly). -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[legend entries={$x$,$x^2$}] - \addplot {x}; - \addplot {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - - The commands for legend creation take precedence: the key is only considered if there is no legend command in the current axis. Please refer to section~\ref{pgfplots:sec:legendcmds}, Legend Commands, for details about the commands. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[legend entries={$x$,$x^2$}] - \addplot {x}; - \addplot {x^2}; - \legend{$a$,$b$}% overrides the option - \end{axis} -\end{tikzpicture} -\end{codeexample} - Please be careful with whitespaces in \marg{comma separated list}: they will contribute to legend entries. Consider using `|%|' at the end of each line in multiline arguments (the end of line character is also a whitespace in \TeX). -\end{pgfplotskey} - -{% -\pgfplotsset{every axis/.append style={width=3cm,scale only axis,legend style={font=\footnotesize}}}% -\begin{stylekey}{/pgfplots/every axis legend} -The style ``|every axis legend|'' determines the legend's position and outer appearance: -\begin{codeexample}[code only] -\pgfplotsset{every axis legend/.append style={ - at={(0,0)}, - anchor=south west}} -\end{codeexample} -will draw it at the lower left corner of the axis while -\begin{codeexample}[code only] -\pgfplotsset{every axis legend/.append style={ - at={(1,1)}, - anchor=north east}} -\end{codeexample} -means the upper right corner. The `|anchor|' option determines which point \emph{of the legend} will be placed at $(0,0)$ or $(1,1)$. - -The legend is a \Tikz-matrix, so one can use any \Tikz\ option which affects -nodes and matrizes (see~\cite[section 13~and~14]{tikz}). The matrix is created by something like -\begin{codeexample}[code only] -\matrix[style=every axis legend] { - draw plot specification 1 & \node{legend 1}\\ - draw plot specification 2 & \node{legend 2}\\ - ... -}; -\end{codeexample} - -\begin{codeexample}[] -\pgfplotsset{every axis legend/.append style={ - at={(1.02,1)}, - anchor=north west}} -\begin{tikzpicture} -\begin{axis} -\addplot coordinates {(0,0) (1,1)}; -\addplot coordinates {(0,1) (1,2)}; -\addplot coordinates {(0,2) (1,3)}; -\legend{$l_1$,$l_2$,$l_3$} -\end{axis} -\end{tikzpicture} -\end{codeexample} - -Use |legend columns=|\marg{number} to configure the number of horizontal legend entries. -\begin{codeexample}[] -\begin{tikzpicture} -\pgfplotsset{every axis legend/.append style={ - at={(0.5,1.03)}, - anchor=south}} -\begin{axis}[legend columns=4] -\addplot coordinates {(0,0) (1,1)}; -\addplot coordinates {(0,1) (1,2)}; -\addplot coordinates {(0,2) (1,3)}; -\legend{$l_1$,$l_2$,$l_3$} -\end{axis} -\end{tikzpicture} -\end{codeexample} -\noindent -Instead of the |.append style|, it is possible to use |legend style| as in the following example. It has the same effect. - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - legend style={ - at={(1,0.5)}, - anchor=east}] -\addplot coordinates {(0,0) (1,1)}; -\addplot coordinates {(0,1) (1,2)}; -\addplot coordinates {(0,2) (1,3)}; -\legend{$l_1$,$l_2$,$l_3$} -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\noindent -The default |every axis legend| style is -\begin{codeexample}[code only] -\pgfplotsset{every axis legend/.style={% - cells={anchor=center},% Centered entries - inner xsep=3pt,inner ysep=2pt,nodes={inner sep=2pt,text depth=0.15em}, - anchor=north east,% - shape=rectangle,% - fill=white,% - draw=black, - at={(0.98,0.98)} -}} -\end{codeexample} -Whenever possible, consider using |.append style| to keep the default styles active. This ensures compatibility with future versions. -\begin{codeexample}[code only] -\pgfplotsset{every axis legend/.append style={...}} -\end{codeexample} -\end{stylekey} - -\pgfplotsshortstylekey legend style=every axis legend\pgfeov - -} - -\begin{pgfplotskey}{legend columns=\marg{number} (default 1)} -Allows to configure the maximum number of adjacent legend entries. The default value~|1| places legend entries vertically below each other. - -Use |legend columns=-1| to draw all entries horizontally. -\end{pgfplotskey} - -\begin{pgfplotskey}{legend plot pos=\mchoice{left,right,none} (initially left)} -Configures where the small line specifications will be drawn: left of the description, right of the description or not at all. -\end{pgfplotskey} - -\begin{pgfplotscodekey}{legend image code} -\label{opt:legend:image:code} -Allows to replace the default images which are drawn inside of legends. The first argument to this option is the plot specification, a key-value list which has been determined by |\addplot|. - -The default is -\begin{codeexample}[code only] -/pgfplots/legend image code/.code={% - \draw[#1,mark repeat=2,mark phase=2] - plot coordinates { - (0cm,0cm) - (0.3cm,0cm) - (0.6cm,0cm)% - };% -} -\end{codeexample} -\end{pgfplotscodekey} - -\begin{stylekey}{/pgfplots/area legend} - A style which sets |legend image code| to -\begin{codeexample}[code only] -\pgfplotsset{ - /pgfplots/legend image code/.code={% - \draw[#1] (0cm,-0.1cm) rectangle (0.6cm,0.1cm); - }} -\end{codeexample} - -% \usetikzlibrary{patterns} -\begin{codeexample}[] -% \usetikzlibrary{patterns} -\begin{tikzpicture} -\begin{axis}[area legend, - axis x line=bottom, - axis y line=left, - domain=0:1, - legend style={at={(0.03,0.97)}, - anchor=north west}, - axis on top,xmin=0] -\addplot[pattern=crosshatch dots, - pattern color=blue,draw=blue] -expression[samples=500] - {sqrt(x)} \closedcycle; - -\addplot[pattern=crosshatch, - pattern color=blue!30!white, - draw=blue!30!white] -expression {x^2} \closedcycle; - -\addplot[red] coordinates {(0,0) (1,1)}; -\legend{$\sqrt x$,$x^2$,$x$} -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{stylekey} - -\subsubsection{Axis Lines} -By default the axis lines are drawn as a |box|, but it is possible to change the appearance of the $x$~and~$y$ axis lines. - -\begin{pgfplotskeylist}{ - axis x line=\mchoice{box,top,middle,center,bottom,none} (initially box), - axis x line*=\mchoice{box,top,middle,center,bottom,none} (initially box), - axis y line=\mchoice{box,left,middle,center,right,none} (initially box), - axis y line*=\mchoice{box,left,middle,center,right,none} (initially box)} -Allows to choose the location of the axis line(s). Ticks and tick labels are placed accordingly. -The choice |bottom| will draw the $x$ line at $y=y_\text{min}$, |middle| will draw the $x$~line at $y=0$, and |top| will draw it at $y=y_\text{max}$. Finally, |box| is a combination of options |top| and |bottom|. The $y$~variant works similarly. - -The case |center| is a synonym for |middle|, both draw the line through the respective coordinate~$0$. If this coordinate is not part of the axis limit, the lower axis limit is chosen instead. - -The starred versions $\dotsc$|line*| \emph{only} affect the axis lines, without correcting the positions of axis labels, tick lines or other keys which are (possibly) affected by a changed axis line. The non-starred versions are actually styles which set the starred key \emph{and} some other keys which also affect the figure layout: -\begin{itemize} - \item In case |axis x line=box|, the style |every boxed x axis| will be installed immediately. - \item In case |axis x line|$\neq$|box|, the style |every non boxed x axis| will be installed immediately. Furthermore, axis labels positions will be adjusted to fit the choosen value. -\end{itemize} -The same holds true for the |y|-variants. The default styles are defined as -\begin{codeexample}[code only] -\pgfplotsset{ - /pgfplots/every non boxed x axis/.style={ - xtick align=center, - enlarge x limits=false, - x axis line style={-stealth} - }, - /pgfplots/every boxed x axis/.style={} -} -\end{codeexample} -Feel free to overwrite these styles if the default doesn't fit your needs or taste. - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - xlabel=$x$,ylabel=$\sin x$] - - \addplot[blue,mark=none] - expression[domain=-10:0,samples=40] - {sin(deg(x))}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - axis x line=middle, - axis y line=right, - ymax=1.1, ymin=-1.1, - xlabel=$x$,ylabel=$\sin x$ -] - \addplot[blue,mark=none] - expression[domain=-10:0,samples=40] - {sin(deg(x))}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - axis x line=bottom, - axis y line=left, - xlabel=$x$,ylabel=$\sqrt{|x|}$ -] -\addplot[blue,mark=none] - expression[domain=-4:4,samples=501] - {sqrt(abs(x))}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - minor tick num=3, - axis y line=center, - axis x line=middle, - xlabel=$x$,ylabel=$\sin x$ - ] - \addplot[smooth,blue,mark=none] - [domain=-5:5,samples=40] - {sin(deg(x))}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - minor tick num=3, - axis y line=left, - axis x line=middle, - xlabel=$x$,ylabel=$\sin x$ - ] - \addplot[smooth,blue,mark=none] - [domain=-5:5,samples=40] - {sin(deg(x))}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -In case |middle|, the style |every inner axis x line| allows to adjust the appearenace. -\end{pgfplotskeylist} - -\begin{pgfplotsxykey}{every inner \x\ axis line} - A style key which can be redefined to customize the appearance of \emph{inner} axis lines. Inner axis lines are those drawn by the |middle| (or |center|) choice of |axis x line|, see above. - - This style affects \emph{only} the line as such. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - minor tick num=1, - axis x line=middle, - axis y line=middle, - every inner x axis line/.append style= - {|->>}, - every inner y axis line/.append style= - {|->>}, - xlabel=$x$,ylabel=$y^3$ -] -\addplot[blue] expression[domain=-3:5] {x^3}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykey} - -\begin{pgfplotsxykey}{every outer \x\ axis line} - Similar to |every inner x axis line|, this style configures the appearance of all axis lines which are part of the outer box. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - separate axis lines, % important ! - every outer x axis line/.append style= - {-stealth}, - every outer y axis line/.append style= - {-stealth}, -] -\addplot[blue] plot[id=DoG, - samples=100, - domain=-15:15] - gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykey} - -\begin{pgfplotskey}{separate axis lines=\marg{true,false} (default true)} - Enables or disables separate path commands for every axis line. This option affects \emph{only} the case if axis lines are drawn as a \emph{box}. - - Both cases have their advantages and disadvantages, I fear there is no reasonable default (suggestions are welcome). - - The case |separate axis lines=true| allows to draw arrow heads on each single axis line, but it can't close edges very well -- in case of thick lines, unsatisfactory edges occur. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - separate axis lines, - every outer x axis line/.append style= - {-stealth,red}, - every outer y axis line/.append style= - {-stealth,green!30!black}, -] -\addplot[blue] - expression[ - samples=100, - domain=-15:15] - {1.3*exp(0-x^2/10) - exp(0-x^2/20)}; - % Unfortunately, there is a bug in PGF 2.00 - % something like exp(-10^2) - % must be written as exp(0-10^2) :-( -\end{axis} -\end{tikzpicture} -\end{codeexample} - - The case |separate axis lines=false| issues just \emph{one} path for all axis lines. It draws a kind of rectangle, where some parts of the rectangle may be skipped over if they are not wanted. The advantage is that edges are closed properly. The disadvantage is that at most one arrow head is added to the path (and yes, only one drawing color is possible). -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - separate axis lines=false, - every outer x axis line/.append style= - {-stealth,red}, - every outer y axis line/.append style= - {-stealth,green!30!black}, -] -\addplot[blue] plot[id=DoG, - samples=100, - domain=-15:15] - gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotskey} - - -\label{pgfplots:page:axislines} -\begin{pgfplotskey}{axis line style=\marg{key-value-list}} - A command which appends \marg{key-value-list} to \emph{all} axis line appearance styles. -\end{pgfplotskey} - -\begin{pgfplotskey}{inner axis line style=\marg{key-value-list}} - A command which appends \marg{key-value-list} to both, |every inner x axis line| and the $y$ variant. -\end{pgfplotskey} -\begin{pgfplotskey}{outer axis line style=\marg{key-value-list}} - A command which appends \marg{key-value-list} to both, |every outer x axis line| and the $y$ variant. -\end{pgfplotskey} -\begin{pgfplotsxykey}{\x\ axis line style=\marg{key-value-list}} - A command which appends \marg{key-value-list} to all axis lines styles for either $x$ or $y$ axis. -\end{pgfplotsxykey} - -\begin{pgfplotsxykey}{every boxed \x\ axis} - A style which will be installed as soon as |axis x line=box| (|y|) is set. - - The default is simply empty. -\end{pgfplotsxykey} -\begin{pgfplotsxykey}{every non boxed \x\ axis} - A style which will be installed as soon as |axis x line| (|y|) will be set to something different than |box|. - - The default is -\begin{codeexample}[code only] -\pgfplotsset{ - /pgfplots/every non boxed x axis/.style={ - xtick align=center, - enlarge x limits=false, - x axis line style={-stealth}}} -\end{codeexample} - \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)} -{% -\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. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - scale only axis, - xmin=-5,xmax=5, - axis y line=left, - xlabel=$x$, - ylabel=First ordinate] - \addplot {x^2}; - \end{axis} - - \begin{axis}[ - scale only axis, - xmin=-5,xmax=5, - 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: -\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. -\end{enumerate} -You may want to consider different legend styles. -It is also possible to use only the axis, without any plots: -% \usepackage{textcomp} -\begin{codeexample}[] -% \usepackage{textcomp} -\begin{tikzpicture} - \begin{axis}[ - scale only axis, - xmin=-5,xmax=5, - axis y line=left, - xlabel=$x$, - ylabel=Absolute] - \addplot {x^2}; - \end{axis} - - \begin{axis}[ - scale only axis, - xmin=-5,xmax=5, - ymin=0,ymax=1000, - yticklabel= -{$\pgfmathprintnumber{\tick}$\textperthousand}, - axis y line=right, - axis x line=none, - y label style={yshift=-10pt}, - ylabel=per thousand] - \end{axis} -\end{tikzpicture} -\end{codeexample} -} - -\subsubsection{Axis Discontinuities} -In case the range of either of the axis do not include the zero value, it is possible to visualize this with a discontinuity decoration on the corresponding axis line. - -\begin{pgfplotsxykey}{axis \x\ discontinuity=\mchoice{crunch,parallel,none} (initially none)} -Insert a discontinuity decoration on the $x$ (or $y$, respectively) axis. -This is to visualize that the $y$ axis does cross the $x$ axis at its $0$ value, because the minimum $x$ axis value is positive or the maximum value is negative. - -The description applies |axis y discontinuity| as well, with interchanged meanings of $x$~and~$y$. - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - axis x line=bottom, - axis x discontinuity=parallel, - axis y line=left, - xmin=360, xmax=600, - ymin=0, ymax=7, - enlargelimits=false -] - \addplot coordinates { - (420,2) - (500,6) - (590,4) - }; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - axis x line=bottom, - axis y line=center, - tick align=outside, - axis y discontinuity=crunch, - ymin=95, enlargelimits=false -] - \addplot[blue,mark=none] - expression[domain=-4:4,samples=20] - {x*x+x+104}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykey} - -A problem might occur with the placement of the ticks on the axis. -This can be solved by specifying the minimum or maximum axis value for which a tick will be placed. - -\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord} (default axis limits), \x tickmax=\marg{coord} (default axis limits)} -\label{key:xytickminmax} -The options |xtickmin|, |xtickmax| and |ytickmin|, |ytickmax| allow to define the axis tick limits, i.e. the axis values before respectively after no ticks will be placed. -Everything outside of the axis tick limits will be not drawn. -Their default values are equal to the axis limits. - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - axis x line=bottom, - axis y line=center, - tick align=outside, - axis y discontinuity=crunch, - xtickmax=3, - ytickmin=110, - ymin=95, enlargelimits=false -] - \addplot[blue,mark=none] - plot[domain=-4:4,samples=20] - expression{x*x+x+104}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykeylist} - -\begin{pgfplotsxykey}{hide \x\ axis=\mchoice{true,false} (initially false)} -Allows to hide either the $x$ or the $y$ axis. No outer rectangle, no tick marks and no labels will be drawn. Only titles and legends will be processed as usual. - -Axis scaling and clipping will be done as if you did not use |hide x axis|. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - hide x axis, - hide y axis, - title={$x^2\cos(x)$}] - \addplot {cos(x)*x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - hide x axis, - axis y line=left, - title={$x^2\cos(x)$}] - \addplot {cos(x)*x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykey} - -\begin{stylekey}{/pgfplots/hide axis=\mchoice{true,false} (default true)} - A style which sets both, |hide x axis| and |hide y axis|. -\end{stylekey} - -\subsubsection{Adjusting Descriptions for Different Scales} -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. - -\begin{keylist}{ - /tikz/font=\mchoice{\textbackslash normalfont,\textbackslash small,\textbackslash tiny,$\dotsc$}, - /pgfplots/max space between ticks=\marg{integer}, - /tikz/mark size=\marg{integer}} - These keys should be adjusted to the figure's dimensions. Use -\begin{codeexample}[code only] -\pgfplotset{tick label style={font=\footnotesize}, - label style={font=\small}, - legend style={font=\small} -} -\end{codeexample} - to provide different fonts for different descriptions. - - The |max space between ticks| is described on page~\pageref{maxspacebetweenticks} and configures the approximate distance between successive tick labels (in |pt|). Please omit the |pt| suffix here. -\end{keylist} - -There are a couple of predefined scaling styles which set some of these options: - -\begin{stylekey}{/pgfplots/normalsize} - Re-initialises the standard scaling options of \PGFPlots. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[normalsize, - title=A ``normalsize'' figure, - xlabel=The $x$ axis, - ylabel=The $y$ axis, - legend entries={Leg}] - \addplot {max(4*x,7*x)}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - - The initial setting is -\begin{codeexample}[code only] -/pgfplots/normalsize/.style={ - /pgfplots/width=240pt, - /pgfplots/height=207pt, - /pgfplots/max space between ticks=35 -} -\end{codeexample} -\end{stylekey} - -\begin{stylekey}{/pgfplots/small} - Redefines several keys such that the axis is ``smaller''. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[small, - title=A ``small'' figure, - xlabel=The $x$ axis, - ylabel=The $y$ axis, - legend entries={Leg}] - \addplot {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - The initial setting is -\begin{codeexample}[code only] -/pgfplots/small/.style={ - /pgfplots/width=6.5cm, - /pgfplots/height=, - /pgfplots/max space between ticks=25 -} -\end{codeexample} -Feel free to redefine the scaling -- the option may still be useful to get more ticks without typing too much. You could, for example, set |small,width=6cm|. -\end{stylekey} - -\begin{stylekey}{/pgfplots/footnotesize} - Redefines several keys such that the axis is even smaller. The tick labels will have |\footnotesize|. - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[footnotesize, - title=A ``footnotesize'' figure, - xlabel=The $x$ axis, - ylabel=The $y$ axis, - legend entries={Leg}] - \addplot+[const plot] - coordinates { - (0,0) (1,1) (3,3) (5,10) - }; - \end{axis} -\end{tikzpicture} -\end{codeexample} - The initial setting is -\begin{codeexample}[code only] -/pgfplots/footnotesize/.style={ - /pgfplots/width=5cm, - /pgfplots/height=, - legend style={font=\footnotesize}, - tick label style={font=\footnotesize}, - label style={font=\small}, - /pgfplots/max space between ticks=20, - every mark/.append style={mark size=8}, - ylabel style={yshift=-0.3cm} -}, -\end{codeexample} -As for |small|, it can be convenient to set |footnotesize| and set |width| afterwards. -\end{stylekey} - -\subsection{Scaling Options} - -\begin{pgfplotskey}{width=\marg{dimen}} -Sets the width of the final picture to \marg{dimen}. If no |height| is specified, scaling will respect aspect ratios. - -\noindent\underline{Remarks:} -\begin{itemize} - \item The scaling only affects the width of one unit in $x$-direction or the height for one unit in $y$-direction. Axis labels and tick labels won't be resized, but their size is used to determine the axis scaling. - - \item You can use the |scale=|\marg{number} option, -\begin{codeexample}[code only] -\begin{tikzpicture}[scale=2] -\begin{axis} -... -\end{axis} -\end{tikzpicture} -\end{codeexample} - to scale the complete picture. - - \item The \Tikz-options |x| and |y| which set the unit dimensions in $x$ and $y$ directions can be specified as arguments to |\begin{axis}[x=1.5cm,y=2cm]| if needed (see below). These settings override the |width| and |height| options. - - \item You can also force a fixed width/height of the axis (without looking at labels) with - \begin{codeexample}[code only] -\begin{tikzpicture} -\begin{axis}[width=5cm,scale only axis] - ... -\end{axis} -\end{tikzpicture} - \end{codeexample} - - \item Please note that up to the writing of this manual, \PGFPlots\ only estimates the size needed for axis- and tick labels. It does not include legends which have been placed outside of the axis\footnote{I.e. the `|width|' option will not work as expected, but the bounding box is still ok.}. This may be fixed in future versions. - - Use the |x=|\marg{dimension}, |y=|\marg{dimension} and |scale only axis| options if the scaling happens to be wrong. -\end{itemize} -\end{pgfplotskey} - -\begin{pgfplotskey}{height=\marg{dimen}} - See |width|. -\end{pgfplotskey} - -\begin{pgfplotskey}{scale only axis=\mchoice{true,false} (initially false)} -If |scale only axis| is enabled, label, tick and legend dimensions won't influence the size of the axis rectangle, that means |width| and |height| apply only to the axis rectangle - -If |scale only axis=false| (the default), \PGFPlots\ will try to produce the desired width \emph{including} labels, titles and ticks. -\end{pgfplotskey} - -\begin{pgfplotsxykeylist}{ - \x=\marg{dimen}, - \x={\{(\meta{x},\meta{y})\}}} -Sets the unit vectors for $x$ (or $y$). Every logical plot coordinate $(x,y)$ is drawn at the position -\[ x \cdot \begin{bmatrix} e_{xx} \\ e_{xy} \end{bmatrix} + y \cdot \begin{bmatrix} e_{yx} \\ e_{yy} \end{bmatrix}. \] -The unit vectors $e_x$ and $e_y$ determine the paper position in the current (always two dimensional) image. - -The key |x=|\marg{dimen} simply sets $e_x = (\meta{dimen},0)^T $ while |y=|\marg{dimen} sets $e_y = (0,\meta{dimen})^T$. -Here, \marg{dimen} is any \TeX\ size like |1mm|, |2cm| or |5pt|. It is allowed to specify a negative \marg{dimen}. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[x=1cm,y=1cm] -\addplot expression[domain=0:3] {2*x}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[x=1cm,y=-0.5cm] -\addplot expression[domain=0:3] {2*x}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})^T$ explicitly\footnote{Please note that you need extra curly braces around the vector. Otherwise, the comma will be interpreted as separator for the next key-value pair.}; the corresponding |y| key works similiarly. This allows to define skewed or rotated axes. - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[x={(1cm,0.1cm)},y=1cm] -\addplot expression[domain=0:3] {2*x}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - x={(5pt,1pt)}, - y={(-4pt,4pt)}] -\addplot {1-x^2}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - - Setting $x$ explicitly overrides the |width| option. Setting $y$ explicitly overrides the |height| option. - - Setting |x| and/or |y| for logarithmic axis will set the dimension used for $1 \cdot e \approx 2.71828$. - - Please note that it is \emph{not} possible to specify |x| as argument to |tikzpicture|. The option -\begin{codeexample}[code only] -\begin{tikzpicture}[x=1.5cm] -\begin{axis} - ... -\end{axis} -\end{tikzpicture} -\end{codeexample} - won't have any effect because an axis rescales its coordinates (see the |width| option). - -\paragraph{Limitations:} Unfortunately, skewed axes are \textbf{not available for bar plots}. -\index{Errors!Skewed axes and bar plots}% -\index{Bar Plots!Skewed axes problems}% -\end{pgfplotsxykeylist} - -\begin{pgfplotskey}{axis equal=\marg{true,false} (initially false)} - Each unit vector is set to the same length while the axis dimensions stay constant. Afterwards, the size ratios for each unit in $x$ and $y$ will be the same. - - Axis limits will be enlarge to compensate for the scaling effect. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[axis equal=false] - \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; - \end{axis} -\end{tikzpicture} -\hspace{1cm} -\begin{tikzpicture} - \begin{axis}[axis equal=true] - \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{loglogaxis}[axis equal=false] - \addplot expression[domain=1:10000] {x^-2}; - \end{loglogaxis} -\end{tikzpicture} -\hspace{1cm} -\begin{tikzpicture} - \begin{loglogaxis}[axis equal=true] - \addplot expression[domain=1:10000] {x^-2}; - \end{loglogaxis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotskey} - -\begin{pgfplotskey}{axis equal image=\marg{true,false} (initially false)} - Similar to |axis equal|, but the axis limits will stay constant as well (leading to smaller images). -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[axis equal image=false] - \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; - \end{axis} -\end{tikzpicture} -\hspace{1cm} -\begin{tikzpicture} - \begin{axis}[axis equal image=true] - \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{loglogaxis}[axis equal image=false] - \addplot expression[domain=1:10000] {x^-2}; - \end{loglogaxis} -\end{tikzpicture} -\hspace{1cm} -\begin{tikzpicture} - \begin{loglogaxis}[axis equal image=true] - \addplot expression[domain=1:10000] {x^-2}; - \end{loglogaxis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotskey} - -\subsection{Error Bars} -\label{sec:errorbars} -{% -\def\pgfplotserror#1{\ensuremath{\epsilon_{#1}}}% -\PGFPlots\ supports error bars for normal and logarithmic plots. - -Error bars are enabled for each plot separately, using \meta{behavior options} after |\addplot|: -\begin{codeexample}[code only] -\addplot plot[error bars/.cd,x dir=both,y dir=both] ... -\end{codeexample} -Error bars inherit all drawing options of the associated plot, but they use their own marker and style arguments additionally. - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot plot[error bars/.cd, - y dir=plus,y explicit] -coordinates { - (0,0) +- (0.5,0.1) - (0.1,0.1) +- (0.05,0.2) - (0.2,0.2) +- (0,0.05) - (0.5,0.5) +- (0.1,0.2) - (1,1) +- (0.3,0.1)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} -\addplot plot[error bars/.cd, - y dir=both,y explicit, - x dir=both,x fixed=0.05, - error mark=diamond*] -coordinates { - (0,0) +- (0.5,0.1) - (0.1,0.1) +- (0.05,0.2) - (0.2,0.2) +- (0,0.05) - (0.5,0.5) +- (0.1,0.2) - (1,1) +- (0.3,0.1)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}} -\begin{codeexample}[] -\pgfplotstabletypeset{pgfplots.testtable2.dat} - -\begin{tikzpicture} -\begin{loglogaxis} -\addplot plot[error bars/.cd, - x dir=both,x fixed relative=0.5, - y dir=both,y explicit relative, - error mark=triangle*] - table[x=x,y=y,y error=errory] - {pgfplots.testtable2.dat}; -\end{loglogaxis} -\end{tikzpicture} -\end{codeexample} -%-------------------------------------------------- -% coordinates { -% (32,32) -% (64,64) -% (128,128) +- (0,0.3) -% (1024,1024) +- (0,0.2) -% (32068,32068) +- (0,0.6) -% (64000,64000) +- (0,0.6) -% (128000,128000) +- (0,0.6) -% }; -%-------------------------------------------------- - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[enlargelimits=false] -\addplot[red,mark=*] - plot[error bars/.cd, - y dir=minus,y fixed relative=1, - x dir=minus,x fixed relative=1, - error mark=none, - error bar style={dotted}] -coordinates - {(0,0) (0.1,0.1) (0.2,0.2) - (0.5,0.5) (1,1)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{pgfplotsxykey}{error bars/\x\ dir=\mchoice{none,plus,minus,both} (initially none)} -Draws either no error bars at all, only marks at $x+\pgfplotserror x$, only marks at $x-\pgfplotserror x$ or marks at both, $x+\pgfplotserror x$ and $x-\pgfplotserror x$. The $x$-error $\pgfplotserror x$ is acquired using one of the following options. - -The same holds for the |y dir| option. -\end{pgfplotsxykey} - -\begin{pgfplotsxykey}{error bars/\x\ fixed=\marg{value} (initially 0)} -Provides a common, absolute error $\pgfplotserror x=\text{\meta{value}}$ for all input coordinates. - -For linear $x$~axes, the error mark is drawn at $x \pm \pgfplotserror x$ while for logarithmic $x$~axes, it is drawn at $\log( x \pm \pgfplotserror x)$. Computations are performed in \PGF's floating point arithmetics. -\end{pgfplotsxykey} - -\begin{pgfplotsxykey}{error bars/\x\ fixed relative=\marg{percent} (initially 0)} -Provides a common, relative error $\pgfplotserror x = \text{\meta{percent}} \cdot x$ for all input coordinates. The argument \meta{percent} is thus given relatively to input $x$ coordinates such that $\text{\meta{percent}} = 1$ means $100\%$. - -Error marks are thus placed at $x \cdot (1 \pm \pgfplotserror x)$ for linear axes and at $\log(x \cdot (1 \pm \pgfplotserror x))$ for logarithmic axes. Computations are performed in floating point for linear axis and using the identity $\log(x \cdot (1 \pm \pgfplotserror x)) = \log(x) + \log( 1 \pm \pgfplotserror x)$ for logarithmic scales. -\end{pgfplotsxykey} - -\begin{pgfplotsxykey}{error bars/\x\ explicit} -Configures the error bar algorithm to draw $x$-error bars at any input coordinate for which user-specified errors are available. - Each error is interpreted as absolute error, see |x fixed| for details. - -The different input formats of errors are described in section~\ref{sec:errorbar:input}. -\end{pgfplotsxykey} - -\begin{pgfplotsxykey}{error bars/\x\ explicit relative} -Configures the error bar algorithm to draw $x$-error bars at any input coordinate for which user-specified errors are available. - Each error is interpreted as relative error, that means error marks are placed at $x (1 \pm \text{\meta{value}}(x))$ (works as for |error bars/x fixed relative|). -\end{pgfplotsxykey} - - -\begin{pgfplotskey}{error bars/error mark=\meta{marker}} -Sets an error marker for any error bar. \marg{marker} is expected to be a valid plot mark, see section~\ref{sec:markers}. -\end{pgfplotskey} - -\begin{pgfplotskey}{error bars/error mark options=\marg{key-value-list}} -Sets a key-value list of options for any error mark. This option works similary to the \Tikz\ `|mark options|' key. -\end{pgfplotskey} - -\begin{pgfplotskey}{error bars/error bar style=\marg{key-value-list}} -Appends the argument to `|/pgfplots/every error bar|' which is installed at the beginning of every error bar. -\end{pgfplotskey} - -\begin{pgfplotscodetwokey}{error bars/draw error bar} -Allows to change the default drawing commands for error bars. The two arguments are -\begin{itemize} -\item the source point, $(x,y)$ and -\item the target point, $(\tilde x,\tilde y)$. -\end{itemize} -Both are determined by \PGFPlots\ according to the options described above. The default code is -\begin{codeexample}[code only] -/pgfplots/error bars/draw error bar/.code 2 args={% - \pgfkeysgetvalue{/pgfplots/error bars/error mark}% - {\pgfplotserrorbarsmark}% - \pgfkeysgetvalue{/pgfplots/error bars/error mark options}% - {\pgfplotserrorbarsmarkopts}% - \draw #1 -- #2 node[pos=1,sloped,allow upside down] {% - \expandafter\tikz\expandafter[\pgfplotserrorbarsmarkopts]{% - \expandafter\pgfuseplotmark\expandafter{\pgfplotserrorbarsmark}% - \pgfusepath{stroke}}% - }; -} -\end{codeexample} -\end{pgfplotscodetwokey} - -\subsubsection{Input Formats of Error Coordinates} -\label{sec:errorbar:input}% -Error bars with explicit error estimations for single data points require some sort of input format. This applies to `|error bars/|\meta{[xy]}| explicit|' and `|error bars/|\meta{[xy]}| explicit relative|'. - -Error bar coordinates can be read from `|plot coordinates|' or from `|plot table|'. The inline plot coordinates format is -\begin{codeexample}[code only] -\addplot coordinates { - (1,2) +- (0.4,0.2) - (2,4) +- (1,0) - (3,5) - (4,6) +- (0.3,0.001) -} -\end{codeexample} -where $(1,2) \pm (0.4,0.2)$ is the first coordinate, $(2,4) \pm (1,0)$ the second and so forth. The point $(3,5)$ has no error coordinate. - -The `|plot table|' format is -\begin{codeexample}[code only] -\addplot table[x error=COLNAME,y error=COLNAME] -\end{codeexample} -or -\begin{codeexample}[code only] -\addplot table[x error index=COLINDEX,y error index=COLINDEX] -\end{codeexample} -These options are used as the `|x|' and `|x index|' options. - -You can supply error coordinates even if they are not used at all; they will be ignored silently in this case. - -}% - -\subsection{Number Formatting Options} -\label{sec:number:printing}% -\PGFPlots\ typeset tick labels rounded to given precision and in configurable number formats. The command to do so is |\pgfmathprintnumber|; it uses the current set of number formatting options. - -These options are described in all detail in the manual for \PGFPlotstable, which comes with \PGFPlots. Please refer to that manual. - -\begin{command}{\pgfmathprintnumber\marg{x}} -Generates pretty-printed output for the (real) number \marg{x}. The input number \marg{x} is parsed using |\pgfmathfloatparsenumber| which allows arbitrary precision. - -Numbers are typeset in math mode using the current set of number printing options, see below. Optional arguments can also be provided using |\pgfmathprintnumber[|\meta{options}|]|\marg{x}. - -Please refer to the manual of \PGFPlotstable\ (shipped with this package) for details about the number options. -\end{command} - -\label{sec:identify:minor:log}% -\begin{pgfplotskey}{log identify minor tick positions=\mchoice{true,false} (initially false)} -Set this to |true| if you want to identify log--plot tick labels at positions -\[ i \cdot 10^j \] -with $i \in \{2,3,4,5,6,7,8,9\},\, j \in \Z$. This may be valueable in conjunction with the `|extra x ticks|' and `|extra y ticks|' options. -\begin{codeexample}[] -\begin{tikzpicture}% -\begin{loglogaxis} - [title=Standard options, - width=6cm] -\addplot coordinates { - (1e-2,10) - (3e-2,100) - (6e-2,200) -}; -\end{loglogaxis} -\end{tikzpicture}% -\end{codeexample} - -\begin{codeexample}[] -\pgfplotsset{every axis/.append style={% - width=6cm, - xmin=7e-3,xmax=7e-2, - extra x ticks={3e-2,6e-2}, - extra x tick style={major tick length=0pt,font=\footnotesize} -}}% - -\begin{tikzpicture}% - \begin{loglogaxis}[ - xtick={1e-2}, - title=with minor tick identification, - extra x tick style={ - log identify minor tick positions=true}] - \addplot coordinates { - (1e-2,10) - (3e-2,100) - (6e-2,200) - }; - \end{loglogaxis} -\end{tikzpicture}% - -\begin{tikzpicture}% - \begin{loglogaxis}[ - xtick={1e-2}, - title=without minor tick identification, - extra x tick style={ - log identify minor tick positions=false}] - \addplot coordinates { - (1e-2,10) - (3e-2,100) - (6e-2,200) - }; - \end{loglogaxis}% -\end{tikzpicture}% -\end{codeexample} - This key is set by the default styles for extra ticks. -\end{pgfplotskey} - -\begin{pgfplotscodekey}{log number format code} -Provides \TeX-code to generate log plot tick labels. Argument `|#1|' is the (natural) logarithm of the tick position. -The default implementation invokes |log base 10 number format code| after it changed the log basis to~$10$. It also checks the other log plot options. -\end{pgfplotscodekey} - - -\begin{pgfplotscodekey}{log base 10 number format code} -Allows to change the overall appearance of base 10 log plot tick labels. The default is -\begin{codeexample}[code only] -log base 10 number format code/.code={% - $10^{\pgfmathprintnumber{#1}}$} -\end{codeexample} -where the `|log plot exponent style|' allows to change number formatting options. -\end{pgfplotscodekey} - -\begin{pgfplotskey}{log plot exponent style=\marg{key-value-list}} -Allows to configure the number format of log plot exponents. This style is installed just before `|log base 10 number format code|' will be invoked. Please note that this style will be installed within the default code for `|log number format code|'. -\begin{codeexample}[] -\pgfplotsset{ - samples=15, - width=7cm, - xlabel=$x$, - ylabel=$f(x)$, - extra y ticks={45}, - legend style={at={(0.03,0.97)}, - anchor=north west}} - -\begin{tikzpicture} -\begin{semilogyaxis}[ - log plot exponent style/.style={ - /pgf/number format/fixed zerofill, - /pgf/number format/precision=1}, - domain=-5:10] - - \addplot {exp(x)}; - \addplot {exp(2*x)}; - - \legend{$e^x$,$e^{2x}$} -\end{semilogyaxis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\pgfplotsset{ - samples=15, - width=7cm, - xlabel=$x$, - ylabel=$f(x)$, - extra y ticks={45}, - legend style={at={(0.03,0.97)}, - anchor=north west}} - -\begin{tikzpicture} -\begin{semilogyaxis}[ - log plot exponent style/.style={ - /pgf/number format/fixed, - /pgf/number format/use comma, - /pgf/number format/precision=2}, - domain=-5:10] - - \addplot {exp(x)}; - \addplot {exp(2*x)}; - - \legend{$e^x$,$e^{2x}$} -\end{semilogyaxis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotskey} - - - - -\subsection{Specifying the Plotted Range} - -\begin{pgfplotsxykeylist}{\x min=\marg{coord},\x max=\marg{coord}} -The options |xmin|, |xmax| and |ymin|, |ymax| allow to define the axis limits, i.e. the lower left and the upper right corner. Everything outside of the axis limits will be clipped away. - -Each missing limit will be determined automatically. - -If $x$-limits have been specified explicitly and $y$-limits are computed automatically, the automatic computation of $y$-limits will only considers points which fall into the specified $x$-range (and vice--versa). The same holds true if, for example, only |xmin| has been provided explicitly: in that case, |xmax| will be updated only for points for which $x \ge $|xmin| holds. This feature can be disabled using |clip limits=false|. - -Axis limits can be increased automatically using the |enlargelimits| option. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis} - \addplot {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[xmin=0] - \addplot {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ymax=10] - \addplot {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykeylist} - -\begin{pgfplotsxykey}{\x mode=\mchoice{normal,linear,log} (initially normal)} -Allows to choose between linear (=normal) or logarithmic axis scaling or logplots for each $x,y$-combination. -\end{pgfplotsxykey} - -\begin{pgfplotskey}{clip limits=\mchoice{true,false} (initially true)} - Configures what to do if some, but not all axis limits have been specified explicitly. In case |clip limits=true|, the automatic limit computation will \emph{only} consider points which do not contradict the explicitly set limits. - - This option has nothing to do with path clipping, it only affects how the axis limits are computed. -\end{pgfplotskey} - -\begin{pgfplotsxykey}{enlarge \x\ limits=\mchoice{true,false,auto,\marg{val}} (initially auto)} -Enlarges the axis size for one axis somewhat if enabled. - -You can set |xmin|, |xmax| and |ymin|, |ymax| to the minimum/maximum values of your data and |enlarge x limits| will enlarge the canvas such that the axis doesn't touch the plots. - -\begin{itemize} - \item The value |true| enlarges all axes. - \item The value |false| uses tight axis limits as specified by the user (or read from input coordinates). - \item The value |auto| will enlarge limits only for axis for which axis limits have been determined automatically. - \item All other values like `|enlarge x limits=0.1|' will enlarge all axis limits relatively (in this example, 10\% of the axis limits will be added at all sides). -\end{itemize} -A small value of |enlarge x limits| may avoid problems with large markers near the boundary. -\end{pgfplotsxykey} - -\begin{stylekey}{/pgfplots/enlargelimits=\mchoice{true,false,auto,\marg{val}} (default true)} - A style which sets |enlarge x limits| and |enlarge y limits| to the specified value. -\end{stylekey} - -\begin{environment}{{pgfplotsinterruptdatabb}} -\index{Bounding Box Control!Disable \protect\emph{data} bounding box modifications} - Everything in \marg{environment contents} will not contribute to the data bounding box. -\end{environment} - -\subsection{Tick and Grid Options} - -\begin{pgfplotsxykey}{\x tick=\mchoice{\textbackslash empty,data,\normalfont\marg{coordinate list}} (initially \marg{})} -The options |xtick| and |ytick| assigns a list of \emph{Positions} where ticks shall be placed. The argument is either the command |\empty|, |data| or a list of coordinates. The choice |\empty| will result in no tick at all. The special value |data| will produce tick marks at every coordinate of the first plot. Otherwise, tick marks will be placed at every coordinate in \marg{coordinate list}. If this list is empty, \PGFPlots\ will compute a default list. - -\marg{coordinate list} will be used inside of a |\foreach \x in |\marg{coordinate list} statement. The format is as follows: -\begin{itemize} - \item |{0,1,2,5,8,1e1,1.5e1}| (a series of coordinates), - \item |{0,...,5}| (the same as |{0,1,2,3,4,5}|), - \item |{0,2,...,10}| (the same as |{0,2,4,6,8,10}|), - \item |{9,...,3.5}| (the same as |{9, 8, 7, 6, 5, 4}|), - \item See \cite[Section~34]{tikz} for a more detailed definition of the options. - \item Please be careful with whitespaces inside of \marg{coordinate list} (at least around the dots). -\end{itemize} -For logplots, \PGFPlots\ will apply $\log(\cdot)$ to each element in `\marg{coordinate list}'. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{loglogaxis}[xtick={12,9897,1468864}] - % see above for this macro: - \plotcoords - \end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - xtick=\empty, - ytick={-2,0.3,3,3.7,4.5}] -\addplot+[smooth] coordinates { - (-2,3) (-1.5,2) (-0.3,-0.2) - (1,1.2) (2,2) (3,5)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\paragraph{Attention:} You can't use the `|...|' syntax if the elements are too large for \TeX! For example, `|xtick=1.5e5,2e7,3e8|' will work (because the elements are interpreted as strings, not as numbers), but `|xtick=1.5,3e5,...,1e10|' will fail because it involves real number arithmetics beyond \TeX's capacities. -\vspace*{0.3cm} - -\noindent -The default choice for tick \emph{positions} in normal plots is to place a tick at each coordinate~$i\cdot h$. The step size~$h$ depends on the axis scaling and the axis limits. It is chosen from a list a ``feasable'' step sizes such that neither too much nor too few ticks will be generated. The default for logplots is to place ticks at positions $10^i$ in the axis' range. Which positions depends on the axis scaling and the dimensions of the picture. If log plots contain just one (or two) positions $10^i$ in their limits, ticks will be placed at positions $10^{i\cdot h}$ with ``feasable'' step sizes $h$ as in the case of linear axis. - -The default tick positions can be reconfigured with -\begin{itemize} -\label{maxspacebetweenticks} - \item `|max space between ticks=|\marg{number}' where the integer argument denotes the maximum space between adjacent ticks in full points. The suffix ``|pt|'' has to be omitted and fractional numbers are not supported. The default is~\axisdefaulttickwidth. - \item `|try min ticks=|\marg{number}' configures a loose lower bound on the number of ticks. It should be considered as a suggestion, not a tight limit. The default is~\axisdefaulttryminticks. This number will increase the number of ticks if `|max space between ticks|' produces too few of them. - \item `|try min ticks log=|\marg{number}' The same for logarithmic axis. -\end{itemize} -The total number of ticks may still vary because not all fractional numbers in the axis' range are valid tick positions. - - -\noindent -The tick \emph{appearance} can be (re-)configured with -\begin{codeexample}[code only] -\pgfplotsset{every tick/.style={very thin,gray}} -\pgfplotsset{every minor tick/.style={}} -\end{codeexample} -or -\begin{codeexample}[code only] -\pgfplotsset{every tick/.append style={very thin,gray}} -\pgfplotsset{every minor tick/.append style={black}} -\end{codeexample} -Please prefer the `|.append style|' versions whenever possible to ensure compatibility with future versions. - -These style commands can be used at any time. The tick line width can be configured with `|major tick length|' and `|minor tick length|'. - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[xtick=data,xmajorgrids] - \addplot coordinates { - (1,2) - (2,5) - (4,6.5) - (6,8) - (10,9) - }; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{loglogaxis}[ - title=A log plot with small axis range] - - \addplot coordinates { - (10,1e-4) - (17,8.3176e-05) - (25,7.0794e-05) - (50,5e-5) - }; -\end{loglogaxis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykey} - -\begin{pgfplotskey}{minor tick num=\marg{number}} - Sets both, |minor x tick num| and |minor y tick num| to \marg{number}. - - Minor ticks will be disabled if the major ticks don't have the same distance. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[minor tick num=1] - \addplot {x^3}; - \addplot {-20*x}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[minor tick num=3] - \addplot {x^3}; - \addplot {-20*x}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\end{pgfplotskey} - -\begin{pgfplotsxykey}{minor \x\ tick num=\marg{number} (initially 0)} - Sets the number of minor tick lines used for linear $x$~or~$y$ axis separately. - - Minor ticks will be disabled if the major ticks don't have the same distance. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[minor x tick num=1, - minor y tick num=3] - \addplot {x^3}; - \addplot {-20*x}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\end{pgfplotsxykey} - -\begin{pgfplotsxykey}{extra \x\ ticks=\marg{coordinate list}} -Adds \emph{additional} tick positions and tick labels to the $x$~or~$y$ axis. `Additional' tick positions do not affect the normal tick placement algorithms, they are drawn after the normal ticks. This has two benefits: first, you can add single, important tick positions without disabling the default tick label generation and second, you can draw tick labels `on top' of others, possibly using different style flags. - - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - xmin=0,xmax=3,ymin=0,ymax=15, - extra y ticks={2.71828}, - extra y tick labels={$e$}, - extra x ticks={2.2}, - extra x tick style={grid=major, - tick label style={ - rotate=90,anchor=east}}, - extra x tick labels={Cut}, -] - \addplot {exp(x)}; - \addlegendentry{$e^x$} -\end{axis} -\end{tikzpicture} -\end{codeexample} -\begin{codeexample}[] -\pgfplotsset{every axis/.append style={width=5.3cm}} -\begin{tikzpicture} -\begin{loglogaxis}[ - xtickten={1,2}, - ytickten={-5,-6}] -\addplot coordinates - {(10,1e-5) (20,5e-6) (40,2.5e-6)}; -\end{loglogaxis} -\end{tikzpicture} - -\begin{tikzpicture} -\begin{loglogaxis}[ - xtickten={1,2}, - ytickten={-5,-6}, - extra x ticks={20,40}, - extra y ticks={5e-6,2.5e-6}] -\addplot coordinates - {(10,1e-5) (20,5e-6) (40,2.5e-6)}; -\end{loglogaxis} -\end{tikzpicture} - -\begin{tikzpicture} -\begin{loglogaxis}[ - log identify minor tick positions=false, - xtickten={1,2}, - ytickten={-5,-6}, - extra x ticks={20,40}, - extra y ticks={5e-6,2.5e-6}] -\addplot coordinates - {(10,1e-5) (20,5e-6) (40,2.5e-6)}; -\end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - -Remarks: -\begin{itemize} -\item Use |extra x ticks| to highlight special tick positions. The use of |extra x ticks| does not affect minor tick/grid line generation, so you can place extra ticks at positions $j\cdot 10^i$ in log--plots. -\item Extra ticks are always typeset as major ticks. - -They are affected by |major tick length| or options like |grid=major|. -\item Use the style |every extra x tick| (|every extra y tick|) to configure the appearance. -\item You can also use `|extra x tick style=|\marg{...}' which has the same effect. -\end{itemize} -\end{pgfplotsxykey} - -\begin{pgfplotskeylist}{ - max space between ticks=\marg{number} (initially 35), - try min ticks=\marg{number} (initially 4), - try min ticks log=\marg{number} (initially 3)} -see Options |xtick| and |ytick| for a description. -\end{pgfplotskeylist} - -\begin{pgfplotskeylist}{tickwidth=\marg{dimension} (initially 0.15cm),major tick length=\marg{dimension} (initially 0.15cm)} - Sets the width of major tick lines. -\end{pgfplotskeylist} - -\begin{pgfplotskeylist}{subtickwidth=\marg{dimension} (initially 0.1cm),minor tick length=\marg{dimension} (initially 0.1cm)} - Sets the width of minor tick lines. -\end{pgfplotskeylist} - -\begin{pgfplotsxykey}{\x tickten=\marg{exponent base 10 list}} -These options allow to place ticks at selected positions $10^k, k \in \text{\marg{exponent base 10 list}}$. They are only used for logplots. The syntax for \marg{exponent base 10 list} is the same as above for |xtick=|\marg{list} or |ytick=|\marg{list}. - -Using `|xtickten={1,2,3,4}|' is equivalent to `|xtick={1e1,1e2,1e3,1e4}|', but it requires fewer computational time and it allows to use the short syntax `|xtickten={1,...,4}|'. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{semilogyaxis}[ - samples=8, - ytickten={-6,-4,...,4}, - domain=0:10] - -\addplot {2^(-2*x + 6)}; -\addlegendentry{$2^{-2x + 6}$} - -% or invoke gnuplot to generate coordinates: -\addplot plot[id=pow2] - gnuplot {2**(-1.5*x -3)}; -\addlegendentry{$2^{-1.5x -3}$} -\end{semilogyaxis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykey} - -\begin{pgfplotsxykey}{\x ticklabels=\marg{label list}} -Assigns a \emph{list} of tick \emph{labels} to each tick position. Tick \emph{positions} are assigned using the |xtick| and |ytick|-options. - -This is one of two options to assign tick labels directly. The other option is |xticklabel=|\marg{command} (or |yticklabel=|\marg{command}). -Option `|xticklabel|' offers higher flexibility while `|xticklabels|' is easier to use. - -The argument \marg{label list} has the same format as for ticks, that means -\begin{codeexample}[code only] -xticklabels={$\frac{1}{2}$,$e$} -\end{codeexample} -Denotes the two--element--list $\{\frac 12, e\}$. The list indices match the indices of the tick positions. If you need commas inside of list elements, use -\begin{codeexample}[code only] -xticklabels={{0,5}, $e$}. -\end{codeexample} - - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - xtick={-1.5,-1,...,1.5}, - xticklabels={% - $-1\frac 12$, - $-1$, - $-\frac 12$, - $0$, - $\frac 12$, - $1$} -] -\addplot[smooth,blue,mark=*] coordinates { - (-1, 1) - (-0.75, 0.5625) - (-0.5, 0.25) - (-0.25, 0.0625) - (0, 0) - (0.25, 0.0625) - (0.5, 0.25) - (0.75, 0.5625) - (1, 1) -}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykey} - - -\begin{pgfplotsxykey}{\x ticklabel=\marg{command}} -Use |xticklabel| or |yticklabel| to change the \TeX-command which creates the tick \emph{labels} assigned to each tick position (see options |xtick| and |ytick|). - -This is one of two options to assign tick labels directly. The other option is `|xticklabels=|\marg{label list}' (or |yticklabels=|\marg{label list}). Option `|xticklabel|' offers higher flexibility while `|xticklabels|' is easier to use. - -The argument \marg{command} can be any \TeX-text. The following commands are valid inside of \marg{command}: -\begin{description} - \item[\textbackslash tick] The current element of option |xtick| (or |ytick|). - \item[\textbackslash ticknum] The current tick number, starting with~0 (a counter). - \item[\textbackslash nexttick] This command is only valid in case if the |x tick label as interval| option is set (or the corresponding variable for~$y$). It will contain the position of the next tick position, that means the right boundary of the tick interval. -\end{description} -The default argument is -\begin{itemize} - \item |\axisdefaultticklabel| for normal plots and - \item |\axisdefaultticklabellog| for logplots, see below. -\end{itemize} -(the same holds for |yticklabel|). The defaults are set to -\begin{codeexample}[code only] -\def\axisdefaultticklabel{% - $\pgfmathprintnumber{\tick}$% -} - -\def\axisdefaultticklabellog{% - \pgfkeysgetvalue{/pgfplots/log number format code/.@cmd}\pgfplots@log@label@style - \expandafter\pgfplots@log@label@style\tick\pgfeov -} -\end{codeexample} -that means you can configure the appearance of linear axis with the number formatting options described in section~\ref{sec:number:printing} and logarithmic axis with |log number format code|, see below. - -You can change the appearance of tick labels with -\begin{codeexample}[code only] -\pgfplotsset{every tick label/.append style={ - font=\tiny, - /pgf/number format/sci}} -\end{codeexample} -and/or -\begin{codeexample}[code only] -\pgfplotsset{every x tick label/.append style={ - above, - /pgf/number format/fixed zerofill}} -\end{codeexample} -and -\begin{codeexample}[code only] -\pgfplotsset{every y tick label/.append style={font=\bfseries}} -\end{codeexample} -Another possibility is to use -\begin{codeexample}[code only] -\begin{axis}[y tick label style={above, - /pgf/number format/fixed zerofill} -] -... -\end{axis} -\end{codeexample} -which has the same effect as the `|every x tick label|' statement above. This is possible for all \PGFPlots-|every|-styles, see section~\ref{sec:styles}. -\end{pgfplotsxykey} - -\begin{pgfplotsxykey}{\x\ tick label as interval=\mchoice{true,false} (initially false)} - Allows to treat tick labels as intervals; that means the tick positions denote the interval boundaries. If there are $n$ positions, $(n-1)$ tick labels will be generated, one for each interval. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[x tick label as interval] - \addplot {3*x}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - This mode enables the use of |\nexttick| inside of |xticklabel| (or |yticklabel|). A common application might be a bar plot. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - ybar interval=0.9, - x tick label as interval, - xmin=2003,xmax=2030, - ymin=0,ymax=140, - xticklabel={ - $\pgfmathprintnumber{\tick}$ - -- $\pgfmathprintnumber{\nexttick}$}, - xtick=data, - x tick label style={ - rotate=90,anchor=east, - /pgf/number format/1000 sep=} -] - - \addplot[draw=blue,fill=blue!40!white] - coordinates - {(2003,40) (2005,100) (2006,15) - (2010,90) (2020,120) (2030,3)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykey} - -\label{sec:scaled:ticks}% -\begin{pgfplotsxykeylist}{ - scaled \x\ ticks=\mchoice{true,false,base 10:{\normalfont\meta{e}},real:{\normalfont\meta{number}},manual:{\normalfont\marg{text}\marg{tick scale code}}} (initially true), - scaled ticks=\mchoice{true,false,base 10:{\normalfont\meta{e}},real:{\normalfont\meta{number}},manual:{\normalfont\marg{text}\marg{tick scale code}\hfill}} (initially true)} -Allows to factor out common exponents in tick labels for \emph{linear axes}. For example, if you have tick labels $20000,40000$ and $60000$, you may want to save some space and write $2,4,6$ with a separate factor `$\cdot 10^4$'. Use `|scaled ticks=true|' to enable this feature. In case |true|, tick scaling will be triggered if the data range is either too large or too small (see below). -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[scaled ticks=true] - \addplot coordinates { - (20000,0.0005) - (40000,0.0010) - (60000,0.0020) - }; -\end{axis} -\end{tikzpicture}% -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[scaled ticks=false] - \addplot coordinates { - (20000,0.0005) - (40000,0.0010) - (60000,0.0020) - }; -\end{axis} -\end{tikzpicture} -\end{codeexample} - - The |scaled ticks| key is a style which simply sets scaled ticks for both, $x$ and $y$. - - The value |base 10:|\meta{e} allows to adjust the algorithm manually. For example, |base 10:3| will divide every tick label by $10^3$: -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[scaled ticks=base 10:3, - /pgf/number format/sci subscript] - \addplot coordinates - {(-0.00001,2e12) (-0.00005,4e12) }; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\noindent Here, the \texttt{sci subscript} option simply saves space. -In general, |base 10:|$e$ will divide every tick by $10^e$. The effect -is not limited by the ``too large or too small'' decisions mentioned -above. - - The value |real:|\meta{number} allows to divide every tick by a fixed \meta{number}. - For example, the following plot is physically ranged from $0$ to $2\pi$, but the tick scaling algorithm is configured to divide every tick label by $\pi$. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - xtick={0,1.5708,...,10}, - domain=0:2*pi, - scaled x ticks={real:3.1415}, - xtick scale label code/.code={$\cdot \pi$}] - \addplot {sin(deg(x))}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - \noindent Setting |scaled ticks=real:|\meta{number} also changes the |tick scale label code| to -\begin{codeexample}[code only] -\pgfkeys{/pgfplots/xtick scale label code/.code={$\cdot \pgfmathprintnumber{#1}$}}. -\end{codeexample} - -A further -- not very useful -- example is shown below. Every $x$ tick label has been divided by $2$, every $y$ tick label by $3$. -\nobreak -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - scaled x ticks=real:2, - scaled y ticks=real:3] - \addplot {x^3}; - \node[pin=135:{$(3,9)$}] at (axis cs:3,9) {}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - - Unfortunately, \meta{number} can't be evaluated with \PGF's math parser (yet) to maintain the full data range accepted by \PGFPlots. - - The last option, |scaled ticks=manual:|\marg{text}\marg{tick scale code} allows even more customization. It allows \emph{full control} over the displayed scaling label \emph{and} the scaling code: \marg{text} is used as-is inside of the tick scaling label while \marg{tick scale code} is supposed to be a one-argument-macro which scales each tick. Example: -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - % warning: the '%' signs are necessary (?) - scaled y ticks=manual:{$+65\,535$}{% - \pgfmathfloatcreate{1}{6.5535}{4}% - \pgfmathfloatsubtract{#1}{\pgfmathresult}% - }, - yticklabel style={ - /pgf/number format/fixed, - /pgf/number format/precision=1}, -] -\addplot plot coordinates { - (0, 65535) - (13, 65535) - (14, 65536) - (15, 65537) - (30, 65537) -}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\noindent The example uses |$+65\,535$| as tick scale label content. Furthermore, it defines the customized tick label formula $y - (+6.5535\cdot 10^4) = y - 65535$ to generate $y$ tick labels. - -The \marg{text} can be arbitrary. It is completely in user control. The second argument, \marg{tick scale code} is supposed to be a one-argument-macro in which |#1| is the current tick position in floating point representation. The macro is expected to assign |\pgfmathresult| (also in floating point representation). The \PGF\ manual~\cite{tikz} contains detailed documentation about its math engine (including floating point\footnote{However, that particular stuff is newer than \PGF\ $2.00$. At the time of this writing, it is only available as (public) CVS version.}). - -This feature may also be used do transform coordinates in case they can't be processed with \PGFPlots: transform them and supply a proper tick scaling method such that tick labels represent the original range. - -If \marg{text} is empty, the tick scale label won't be drawn (and no space will be occupied). - -Tick scaling does \emph{not} work for logarithmic axes. -\end{pgfplotsxykeylist} - -\begin{pgfplotsxycodekeylist}{\x tick scale label code} -Allows to change the default code for scaled tick labels. The default is -\begin{codeexample}[code only] -xtick scale label code/.code={$\cdot 10^{#1}$}. -\end{codeexample} - -If the code is empty, no tick scale label will be drawn (and no space is consumed). -\end{pgfplotsxycodekeylist} - -\begin{pgfplotscodekey}{tick scale label code} - A style which sets both, |xtick scale label code| and the corresponding variant for $y$. -\end{pgfplotscodekey} - -\begin{pgfplotskey}{scale ticks below=\marg{exponent}} -Allows fine tuning of the `|scaled ticks|' algorithm: if the axis limits are of magnitude $10^e$ and $e<$\marg{exponent}, the common prefactor~$10^e$ will be factored out. The default is -\makeatletter -\pgfplots@scale@ticks@below@exponent -\makeatother. -\end{pgfplotskey} - -\begin{pgfplotskey}{scale ticks above=\marg{exponent}} -Allows fine tuning of the '|scaled ticks|' algorithm: if the axis limits are of magnitude $10^e$ and $e>$\marg{exponent}, the common prefactor~$10^e$ will be factored out. The default is -\makeatletter -\pgfplots@scale@ticks@above@exponent -\makeatother. -\end{pgfplotskey} - - -\begin{pgfplotsxykey}{\x tick pos=\mchoice{left,right,both} (initially both)} -Allows to choose where to place the small tick lines. In the default configuration, this does also affect tick \emph{labels}, see below. - -For $x$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $y$. -\end{pgfplotsxykey} - -\begin{pgfplotskey}{tickpos=\mchoice{left,right,both}} - A style which sets both, |xtick pos| and |ytick pos|. -\end{pgfplotskey} - -\begin{pgfplotsxykey}{\x ticklabel pos=\mchoice{left,right,default} (initially default)} -Allows to choose where to place tick \emph{labels}. The choices |left| and |right| place tick labels either at the left or at the right side of the complete axis. The choice |default| uses the same setting as |xtick pos| (or |ytick pos|). This option is only useful for boxed axis -- keep it to |default| for non-boxed figures. - -For $x$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $x$. -\end{pgfplotsxykey} - -\begin{pgfplotskey}{ticklabelpos=\mchoice{left,right,default}} - A style which sets both, |xticklabel pos| and |yticklabel pos|. -\end{pgfplotskey} - -\begin{pgfplotsxykey}{\x tick align=\mchoice{inside,center,outside} (initially inside)} -Allows to change the location of the ticks relative to the axis lines. -Default is ``|inside|''. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - xtick=data,ytick=data, - xtick align=center, - axis x line=center, - axis y line=center, - enlargelimits=0.05] -\addplot coordinates - {(-3,0) (-2,0.1) (-1,-0.6) - (0,1) - (1,-0.6) (2,0.1) (3,0)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - xtick=data,ytick=data, - axis x line=bottom, - ytick align=outside, - axis y line=left, - enlargelimits=0.05] -\addplot coordinates - {(-3,0) (-2,0.1) (-1,-0.6) - (0,1) - (1,-0.6) (2,0.1) (3,0)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - xtick=data, - axis x line=center, - xticklabels={,,}, - ytick={-0.6,0,0.1,1}, - yticklabels={ - $-\frac{6}{10}$,, - $\frac{1}{10}$,$1$}, - ymajorgrids, - axis y line=left, - enlargelimits=0.05] -\addplot coordinates - {(-3,0) (-2,0.1) (-1,-0.6) - (0,1) - (1,-0.6) (2,0.1) (3,0)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotsxykey} - -\begin{stylekey}{/pgfplots/tick align=\mchoice{inside,center,outside} (initially inside)} - A style which sets both, |xtick align| and |ytick align| to the specified value. -\end{stylekey} - - -\begin{pgfplotsxykeylist}{\x minorticks=\mchoice{true,false} (initially true),\x majorticks=\mchoice{true,false} (initially true),ticks=\mchoice{minor,major,both,none} (initially both)} -Enables/disables the small tick lines either for single axis or for all of them. Major ticks are those placed at the tick positions and minor ticks are between tick positions. Please note that minor ticks are automatically disabled if |xtick| is not a uniform range\footnote{A uniform list means the difference between all elements is the same for linear axis or, for logarithmic axes, $\log(10)$.}. - -The key |minor tick length=|\marg{dimen} configures the tick length for minor ticks while the |major| variant applies to major ticks. -You can configure the appearance using the following styles: -\begin{codeexample}[code only] -\pgfplotsset{every tick/.append style={color=black}} % applies to major and minor ticks, -\pgfplotsset{every minor tick/.append style={thin}} % applies only to minor ticks, -\pgfplotsset{every major tick/.append style={thick}} % applies only to major ticks. -\end{codeexample} -There is also the style ``|every tick|'' which applies to both, major and minor ticks. -\end{pgfplotsxykeylist} - - -\begin{pgfplotsxykeylist}{\x minorgrids=\mchoice{true,false} (initially true),\x majorgrids=\mchoice{true,false} (initially true),grids=\mchoice{minor,major,both,none} (initially both)} -Enables/disables different grid lines. Major grid lines are placed at the normal tick positions (see |xmajorticks|) while minor grid lines are placed at minor ticks (see |xminorticks|). - -This example employs the coordinates defined on page~\pageref{page:plotcoords:src}. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{loglogaxis}[ - xlabel={\textsc{Dof}}, - ylabel={$L_2$ Error}, - grid=major -] -% see above for this macro: -\plotcoords -\end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} -\begin{loglogaxis}[ - grid=both, - tick align=outside, - tickpos=left] -\addplot coordinates - {(100,1e-4) (500,1e-5) (1000,3e-6)}; -\addplot coordinates - {(100,1e-5) (500,4e-6) (1000,2e-6)}; -\end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - -Grid lines will be drawn before tick lines are processed, so ticks will be drawn on top of grid lines. You can configure the appearance of grid lines with the styles -\begin{codeexample}[code only] -\pgfplotsset{every axis grid/.style={style=help lines}} -\pgfplotsset{every minor grid/.append style={color=blue}} -\pgfplotsset{every major grid/.append style={thick}} -\end{codeexample} -\end{pgfplotsxykeylist} - -\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord}, \x tickmax=\marg{coord}} - These keys can be used to modify minimum/maximum values before ticks are drawn. Because this applies to axis discontinuities, it is described on page~\pageref{key:xytickminmax} under section~\ref{key:xytickminmax}, ``Axis Discontinuities"'. -\end{pgfplotsxykeylist} - - - - - -\subsection{Style Options} -\label{sec:styles} -\subsubsection{All Supported Styles} -\PGFPlots\ provides many styles to customize its appearance and behavior. They can be defined and changed in any place where keys are allowed. Furthermore, own styles are defined easily. - -\begin{handler}{{.style}=\marg{key-value-list}} - Defines or redefines a style \meta{key}. A style is a normal key which will set all options in \marg{key-value-list} when it is set. - - Use |\pgfplotsset{|\meta{key}|/.style={|\meta{key-value-list}|}}| to (re-) define a style \meta{key} in the namespace |/pgfplots|. -\end{handler} - -\begin{handler}{{.append style}=\marg{key-value-list}} - Appends \marg{key-value-list} to an already existing style \meta{key}. This is the preferred method to change the predefined styles: if you only append, you maintain compatibility with future versions. - - Use |\pgfplotsset{|\meta{key}|/.append style={|\meta{key-value-list}|}}| to append \marg{key-value-list} to the style \meta{key}. This will assume the prefix |/pgfplots|. -\end{handler} - -\subsubsection*{Styles installed for linear/logarithmic axis} - -\begin{stylekey}{/pgfplots/every axis (initially empty)} - Installed at the beginning of every axis. \Tikz\ options inside of it will be used for anything inside of the axis rectangle and any axis descriptions. -\end{stylekey} - -\begin{stylekey}{/pgfplots/every semilogx axis (initially empty)} - Installed at the beginning of every plot with linear $x$~axis and logarithmic $y$~axis, but after `|every axis|'. -\end{stylekey} - -\begin{stylekey}{/pgfplots/every semilogy axis (initially empty)} - Likewise, but with interchanged roles for $x$~and~$y$. -\end{stylekey} - -\begin{stylekey}{/pgfplots/every loglog axis (initially empty)} - Installed at the beginning of every double--logarithmic plot. -\end{stylekey} - -\begin{stylekey}{/pgfplots/every linear axis (initially empty)} - Installed at the beginning of every plot with normal axis scaling. -\end{stylekey} - -\subsubsection*{Styles installed for single plots} - -\begin{stylekey}{/pgfplots/every axis plot (initially empty)} - Installed for each plot. This style may contain \meta{behavior options} like samples, gnuplot parameters, error bars and it may contain \meta{style options} which affect the final drawing commands. -\end{stylekey} - -\begin{stylekey}{/pgfplots/every axis plot post (initially empty)} - This style is similar to |every axis plot| in that is applies to any drawing command in |\addplot|. However, it is set \emph{after} any user defined styles or |cycle list| options. -\begin{codeexample}[] -\begin{tikzpicture} -\pgfplotsset{ - every axis plot post/.append style= - {mark=none}} - -\begin{axis}[ - legend style={ - at={(0.03,0.97)},anchor=north west}, - domain=0:1] - \addplot {x^2}; - \addplot {exp(x)}; - \legend{$x^2$,$e^x$} -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{stylekey} - -\begin{stylekey}{/pgfplots/every axis plot no \# (initially empty)} - Used for every \#th plot where $\#=0,1,2,3,4,\dotsc$. This option may also contain \meta{behavior options}. -\end{stylekey} - -\begin{stylekey}{/pgfplots/every forget plot (initially empty)} - Used for every plot which has |forget plot| activated. This option may also contain \meta{behavior options}. -\end{stylekey} - -\subsubsection*{Styles for axis descriptions} - -\begin{stylekey}{/pgfplots/every axis label (initially empty)} - Used for $x$~and~$y$ axis label. You can use `|at=|\parg{x,y} to set its position where $(0,0)$ refers to the lower left corner and $(1,1)$ to the upper right one. -\end{stylekey} - -\pgfplotsshortstylekey label style=every axis label\pgfeov - -\begin{xystylekey}{/pgfplots/every axis \x\ label} - Used only~$x$ or only for~$y$ labels, installed after `|every axis label|'. - - The initial settings are -\begin{codeexample}[code only] -\pgfplotsset{ - every axis x label/.style={at={(0.5,0)},below,yshift=-15pt}, - every axis y label/.style={at={(0,0.5)},xshift=-35pt,rotate=90}} -\end{codeexample} - - The predefined node |current axis| can be used to refer to anchors of the unfinished picture. For example - `|at={(current axis.origin)}|' will position a label at the \emph{data} coordinate $(0,0)$. More useful is probably - `|at={(current axis.right of origin)}|', see - section~\ref{pgfplots:sec:align} for more details. This remark holds - for any axis description, but it is mostly useful for axis labels. - -\paragraph{Attention:} These styles will be overwritten by |axis x line| and/or |axis y line|. Please remember to place your modifications after the axis line variations. -\end{xystylekey} - -\pgfplotsshortxystylekeys \x\ label style,\x label style=every axis \x\ label\pgfeov - -\begin{stylekey}{/pgfplots/every axis title} - Used for any axis title. The |at=|\parg{x,y} command works as for `|every axis label|'. - -The initial setting is -\begin{codeexample}[code only] -\pgfplotsset{every axis title/.style={at={(0.5,1)},above,yshift=6pt}} -\end{codeexample} -\end{stylekey} - -\pgfplotsshortstylekey title style=every axis title\pgfeov - -\begin{stylekey}{/pgfplots/every axis legend} - Installed for each legend. As for |every axis label|, the legend's position can be placed using coordinates between $0$~and~$1$, see above. - - The initial setting is -\begin{codeexample}[code only] -\pgfplotsset{every axis legend/.style={ - cells={anchor=center}, - inner xsep=3pt,inner ysep=2pt,nodes={inner sep=2pt,text depth=0.15em}, - anchor=north east, - shape=rectangle, - fill=white,draw=black, - at={(0.98,0.98)}}} -\end{codeexample} -\end{stylekey} - -\pgfplotsshortstylekey legend style=every axis legend\pgfeov - -\subsubsection*{Styles for axis lines} -\begin{xystylekey}{/pgfplots/every outer \x\ axis line (initially empty)} - Installed for every axis line which lies on the outer box. - - If you want arrow heads, you may also need to check the |separate axis lines| boolean key. -\end{xystylekey} - -\begin{xystylekey}{/pgfplots/every inner \x\ axis line (initially empty)} - Installed for every axis line which is drawn using the |center| or |middle| options. -\end{xystylekey} - -\begin{pgfplotsxykeylist}{% - axis line style=\marg{key-value-list}, - inner axis line style=\marg{key-value-list}, - outer axis line style=\marg{key-value-list}, - \x\ axis line style=\marg{key-value-list}} - These options modify selects parts of the axis line styles. They set |every inner x axis line| and |every outer x axis line| and the respective $y$ variants. -\end{pgfplotsxykeylist} - -\noindent -Please refer to section~\ref{pgfplots:page:axislines} on page~\pageref{pgfplots:page:axislines} for details about styles for axis lines. - - - -\subsubsection*{Styles for ticks} - -\begin{stylekey}{/pgfplots/every tick (initially very thin,gray)} - Installed for each of the small tick \emph{lines}. -\end{stylekey} - -\pgfplotsshortstylekey tick style=every tick\pgfeov - -\begin{stylekey}{/pgfplots/every minor tick (initially empty)} - Used for each minor tick line, installed after `|every tick|'. -\end{stylekey} - -\pgfplotsshortstylekey minor tick style=every minor tick\pgfeov - -\begin{stylekey}{/pgfplots/every major tick (initially empty)} - Used for each major tick line, installed after `|every tick|'. -\end{stylekey} - -\pgfplotsshortstylekey major tick style=every major tick\pgfeov - -\begin{stylekey}{/pgfplots/every tick label (initially empty)} - Used for each $x$~and~$y$ tick labels. -\end{stylekey} - -\begin{xystylekey}{/pgfplots/every \x\ tick label (initially empty)} - Used for each $x$ (or $y$, respectively) tick label, installed after `|every tick label|'. -\end{xystylekey} - -\pgfplotsshortxystylekeys \x\ tick label style,\x ticklabel style=every \x\ tick label\pgfeov - -\begin{xystylekey}{/pgfplots/every \x\ tick scale label} - Configures placement and display of the nodes containing the order of magnitude of tick labels, see section~\ref{sec:scaled:ticks} for more information about |scaled ticks|. - -The initial settings are -\begin{codeexample}[code only] -\pgfplotsset{ - every x tick scale label/.style={at={(1,0)},yshift=-2em,left,inner sep=0pt}, - every y tick scale label/.style={at={(0,1)},above right,inner sep=0pt,yshift=0.3em}} -\end{codeexample} -\end{xystylekey} - -\pgfplotsshortxystylekey \x\ tick scale label style=every \x\ tick scale label\pgfeov - -\begin{xystylekey}{/pgfplots/every \x\ tick (initially empty)} - Installed for tick \emph{lines} on either $x$ or $y$ axis. -\end{xystylekey} - -\pgfplotsshortxystylekey \x\ tick style=every \x\ tick\pgfeov - -\begin{xystylekey}{/pgfplots/every minor \x\ tick (initially empty)} - Installed for minor tick lines on either $x$ or $y$ axis. -\end{xystylekey} - -\pgfplotsshortxystylekey minor \x\ tick style=every minor \x\ tick\pgfeov - -\begin{xystylekey}{/pgfplots/every major \x\ tick (initially empty)} - Installed for major tick lines on either $x$ or $y$ axis. -\end{xystylekey} -\pgfplotsshortxystylekey major \x\ tick style=every major \x\ tick\pgfeov - -\begin{xystylekey}{/pgfplots/every extra \x\ tick} - Allows to configure the appearance of `|extra x ticks|'. This style is installed before touching the first extra $x$~tick. It is possible to set any option which affects tick or grid line generation. - -The initial setting is -\begin{codeexample}[code only] -\pgfplotsset{ - every extra x tick/.style={/pgfplots/log identify minor tick positions=true}, - every extra y tick/.style={/pgfplots/log identify minor tick positions=true}} -\end{codeexample} - - Useful examples are shown below. -\begin{codeexample}[code only] -\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}} -\end{codeexample} -\end{xystylekey} - -\pgfplotsshortxystylekey extra \x\ tick style=every extra \x\ tick\pgfeov - - - -\subsubsection*{Styles for grid lines} - -\begin{stylekey}{/pgfplots/every axis grid (initially thin,black!25)} - Used for each grid line. -\end{stylekey} - -\pgfplotsshortstylekey grid style=every axis grid\pgfeov - -\begin{stylekey}{/pgfplots/every minor grid (initially empty)} - Used for each minor grid line, installed after `|every axis grid|'. -\end{stylekey} - -\pgfplotsshortstylekey minor grid style=every minor grid\pgfeov - -\begin{stylekey}{/pgfplots/every major grid (initially empty)} - Likewise, for major grid lines. -\end{stylekey} - -\pgfplotsshortstylekey major grid style=every major grid\pgfeov - -\begin{xystylekey}{/pgfplots/every axis \x\ grid (initially empty)} - Used for each grid line in either $x$ or $y$ direction. -\end{xystylekey} - -\pgfplotsshortxystylekey \x\ grid style=every axis \x\ grid\pgfeov - -\begin{xystylekey}{/pgfplots/every minor \x\ grid (initially empty)} - Used for each minor grid line in either $x$ or $y$ direction. -\end{xystylekey} - -\pgfplotsshortxystylekey minor \x\ grid style=every minor \x\ grid\pgfeov - -\begin{xystylekey}{/pgfplots/every major \x\ grid (initially empty)} - Used for each major grid line in either $x$ or $y$ direction. -\end{xystylekey} - -\pgfplotsshortxystylekey major \x\ grid style=every major \x\ grid\pgfeov - -\subsubsection*{Styles for error bars} - -\begin{stylekey}{/pgfplots/every error bar (initially thin)} - Installed for every error bar. -\end{stylekey} - -\pgfplotsshortstylekey error bars/error bar style=every error bar\pgfeov - -\subsubsection{(Re-)Defining Own Styles} -\label{sec:styles:own}% -Use |\pgfplotsset{|\meta{style name}|/.style=|\marg{key-value-list}|}| -to create own styles. If \meta{style name} exists already, it will be replaced. Please note that it is \emph{not} possible to use the \Tikz-command |\tikzstyle|\marg{style name}|=[]| in this context\footnote{This was possible in a previous version and is still supported for backwards compatibility. But in some cases, it may not work as expected.}. -\begin{codeexample}[] -\pgfplotsset{my personal style/.style= - {grid=major,font=\large}} - -\begin{tikzpicture} -\begin{axis}[my personal style] - \addplot coordinates {(0,0) (1,1)}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - -\subsection{Alignment Options and Bounding Box Control} -\label{pgfplots:sec:align} - -\begin{pgfplotskey}{anchor=\marg{name} (initially south west)} -\label{option:anchor}% -This option shifts the axis horizontally and vertically such that the axis anchor (a point on the axis) is placed at coordinate $(0,0)$. - -Anchors are useful in conjunction with horizontal or vertical alignment of plots, see the examples below. - -There are four sets of anchors available: anchors positioned on the axis rectangle, anchors on the outer bounding box and anchors which have one coordinate on the outer bounding box and the other one at a position of the axis rectangle. Finally, one can place anchors near the origin. - -{% -%\pgfplotsset{every picture/.append style={background rectangle/.style={help lines},show background rectangle}}% -\pgfplotstableread{pgfplots.testplot}\plottable -\def\plot{% - \begin{axis}[ - width=5cm, - name=test plot, - xlabel=$x$, - ylabel={$y$},% = \frac 12 \cdot x^3 - 4 x^2 -16 x$}, - y label style={yshift=-15pt}, - legend style={at={(1.03,1)},anchor=north west}, - title=A test plot. - ] - \addplot table from{\plottable}; - %\addplot coordinates {(0,0) (1,1)}; - \addlegendentry{$f(x)$} - \addplot[red] plot[id=gnuplot_ppp,domain=-40:40,samples=120] gnuplot{10000*sin(x/3)}; - \addlegendentry{$g(x)$} - \end{axis} -}% -\def\showit#1#2{% - %\node[show them,#2] at (test plot.#1) {(s.#1)}; - \node[pin=#2:(s.#1),fill=black,circle,scale=0.3] at (test plot.#1) {}; -}% -In more detail, we have -\tikzstyle{every pin}=[opacity=0.5,fill=yellow,rectangle,rounded corners=3pt,font=\tiny] -Anchors on the axis rectangle, - \begin{center} - \begin{tikzpicture} - \plot - \showit{north}{90} - \showit{north west}{135} - \showit{west}{180} - \showit{south west}{225} - \showit{south}{270} - \showit{south east}{305} - \showit{east}{0} - \showit{north east}{45} - \showit{center}{90} - \end{tikzpicture} - \end{center} -Anchors on the outer bounding box, - \begin{center} - \begin{tikzpicture} - \plot - \showit{outer north}{90} - \showit{outer north west}{135} - \showit{outer west}{180} - \showit{outer south west}{225} - \showit{outer south}{270} - \showit{outer south east}{305} - \showit{outer east}{0} - \showit{outer north east}{45} - \showit{outer center}{90} - \end{tikzpicture} - \end{center} -There are anchors which have one coordinate on the outer bounding box, and one on the axis rectangle, - \begin{center} - \begin{tikzpicture} - \plot - {\pgfplotsset{every pin/.append style={pin distance=1cm}}% - \showit{above north}{90} - }% - \showit{above north east}{90} - \showit{right of north east}{0} - \showit{right of east}{0} - \showit{right of south east}{0} - \showit{below south east}{-90} - {\pgfplotsset{every pin/.append style={pin distance=1cm}}% - \showit{below south}{-90} - }% - \showit{below south west}{-90} - \showit{left of south west}{180} - \showit{left of west}{180} - \showit{left of north west}{180} - \showit{above north west}{90} - \end{tikzpicture} - \end{center} -And finally, we have origin anchors which are especially useful when axis lines pass through the origin, - \begin{center} - \begin{tikzpicture} - \begin{axis}[ - name=test plot, - axis x line=center, - axis y line=center, - enlargelimits=false, - minor tick num=3, - tick style={semithick}, - tick align=center, - xlabel=$x$, - ylabel=$y$, - every axis x label/.style={at={(current axis.right of origin)},anchor=north east}, - every axis y label/.style={at={(current axis.above origin)},anchor=north east}, - inner axis line style={->}, - ] - \addplot plot[domain=-2:5] {20*x}; - \end{axis} - {\pgfplotsset{every pin/.append style={pin distance=1cm}}% - \showit{above origin}{45} - }% - \showit{right of origin}{45} - {\pgfplotsset{every pin/.append style={pin distance=1cm}}% - \showit{below origin}{0} - }% - \showit{left of origin}{135} - \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. -} - -\begin{description} -\item[Vertical alignment with \texttt{baseline}] -\label{sec:align}% -The default axis anchor is |south west|, which means that the picture coordinate $(0,0)$ is the lower left corner of the axis. As a consequence, the \Tikz\ option ``|baseline|'' allows vertical alignment of adjacent plots: -\begin{codeexample}[] -\pgfplotsset{domain=-1:1} -\begin{tikzpicture} - \begin{axis}[xlabel=A normal sized $x$ label] - \addplot[smooth,blue,mark=*] {x^2}; - \end{axis} -\end{tikzpicture}% -\hspace{0.15cm} -\begin{tikzpicture} - \begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }] - \addplot[smooth,blue,mark=*] {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\pgfplotsset{domain=-1:1} -\begin{tikzpicture}[baseline] - \begin{axis}[xlabel=A normal sized $x$ label] - \addplot[smooth,blue,mark=*] {x^2}; - \end{axis} -\end{tikzpicture}% -\hspace{0.15cm} -\begin{tikzpicture}[baseline] - \begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }] - \addplot[smooth,blue,mark=*] {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -The |baseline| option configures \Tikz\ to shift position $y=0$ to the text's baseline and the |south west| anchor shifts the axis such the $y=0$ is at the lower left axis corner. - - -\item[Horizontal Alignment] -\label{sec:halign}% -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={ -cycle list={ - {red,only marks,mark options={ - fill=red,scale=0.8},mark=*}, - {black,only marks,mark options={ - fill=black,scale=0.8},mark=square*}}}} - -\begin{axis}[width=4cm,scale only axis, - name=main plot] -\addplot file - {plotdata/pgfplots_scatterdata1.dat}; -\addplot file - {plotdata/pgfplots_scatterdata2.dat}; -\addplot[blue] coordinates { - (0.093947, -0.011481) - (0.101957, 0.494273) - (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)}, - anchor=north west, - width=4cm,scale only axis,height=0.8cm, - ytick=\empty] - -\addplot file - {plotdata/pgfplots_scatterdata1_latent.dat}; -\addplot file - {plotdata/pgfplots_scatterdata2_latent.dat}; -\end{axis} -\end{tikzpicture} -\end{codeexample} - - -\item[Bounding box restrictions] Bounding box restrictions can be realized with several methods of \PGF: -\begin{enumerate} - \item The |overlay| option, - \item The |pgfinterruptboundingbox| environment, - \item The |\useasboundingbox| path. -\end{enumerate} -\begin{key}{/tikz/overlay} -\index{Bounding Box Control!Excluding Image Parts} - A special key of \PGF\ which disables bounding box updates for (parts of) the image. The effect is that those parts are an ``overlay'' over the document. - - For \PGFPlots, |overlay| can be useful to position legends or other axis descriptions outside of the axis~-- without affecting its size (and without affecting alignment). - -For example, one may want to include only certain parts of the axis into the final bounding box. This would allow horizontal alignment (centering): -\begin{codeexample}[] -\begin{tikzpicture}% - \begin{axis}[ - title=A title, - ylabel style={overlay}, - yticklabel style={overlay}, - xlabel={$x$}, - ylabel={$y$}, - legend style={at={(0.5,0.97)}, - anchor=north,legend columns=-1}, - domain=-2:2 - ] - \addplot {x^2}; - \addplot {x^3}; - \addplot {x^4}; - \legend{$x^2$,$x^3$,$x^4$} - \end{axis} -\end{tikzpicture}% -\end{codeexample} -\noindent Now, the left axis descriptions ($y$ label and $y$ ticks) stick out of the bounding box. - -The following example places a legend somewhere without affecting the bounding box. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - domain=0:6.2832,samples=200, - legend style={ - overlay, - at={(-0.5,0.5)}, - anchor=center}, - every axis plot post/.append style={mark=none}, - enlargelimits=false] - - \addplot {sin(deg(x)+3)+rand*0.05}; - \addplot {cos(deg(x)+2)+rand*0.05}; - \legend{Signal 1,Signal 2} - \end{axis} -\end{tikzpicture} -\end{codeexample} - - More information about the |overlay| option can be found in the \PGF\ manual~\cite{tikz}. -\end{key} - - -\label{sec:bounding:box:example}% -\index{Bounding Box Control} -\index{Bounding Box Control!pgfinterruptboundingbox} -{% -An alternative to |overlay| is shown below: the figure has a truncated bounding box with is shown using |\fbox|. -\begin{codeexample}[] -\setlength{\fboxsep}{0pt}% -\fbox{% -\begin{tikzpicture}% - \begin{pgfinterruptboundingbox} - \begin{axis}[ - name=my plot, - 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} - \end{pgfinterruptboundingbox} - - \useasboundingbox - (my plot.below south west) - rectangle (my plot.above north east); -\end{tikzpicture}% -}% -\end{codeexample}% -}% -The |pgfinterruptboundingbox| environment does not include its content into the image's bounding box, and |\useasboundingbox| sets the pictures bounding box to the following argument (see~\cite{tikz}). - -\end{description} -\end{pgfplotskey} - -\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. -\end{predefinednode} - -\begin{pgfplotskey}{at=\marg{coordinate expression}} -Assigns a position for the complete axis image. This option works similarly to the |at|-option of |\node[at=|\marg{coordinate expression}|]|, see~\cite{tikz}. The common syntax is |at={|\parg{x,y}|}|. -\end{pgfplotskey} - -\subsection{Symbolic Coordinates and User Transformations} -\label{pgfplots:sec:symbolic:coords} -\PGFPlots\ supports user transformations which can be applied to input and output coordinates. Suppose the plot shall display days versus account statements over time. Then, one wants to visualize date versus credit balance. But: dates need to be transformed to numbers before doing so! Furthermore, tick labels shall be displayed as dates as well. This, and more general transformations, can be realized using the |x coord trafo| and |y coord trafo| keys. - -\begin{pgfplotsxycodekeylist}{ - \x\ coord trafo, - \x\ coord inv trafo} - These code keys allow arbitrary coordinate transformations which are applied to input coordinates and output tick labels. - - The |x coord trafo| and |y coord trafo| command keys take one argument which is the input coordinate. They are expected to set |\pgfmathresult| to the final value. - - At this level, the input coordinate is provided as it is found in the |\addplot| statement. For example, if $x$ coordinates are actually of the form \meta{year}-\meta{month}-\meta{day}, for example |2008-01-05|, then a useful coordinate transformation would transform this string into a number (see below for a predefined realization). - - In short, \emph{no} numerics has been applied to input coordinates when this transformation is applied\footnote{Of course, if coordinates have been generated by gnuplot or \pgfname, this does no longer hold.}. - - The input coordinate transformation is applied to - \begin{itemize} - \item any input coordinates (specified with |\addplot| or |axis cs|), - \item any user-specified |xtick| or |ytick| options, - \item any user-specified |extra x ticks| and |extra y ticks| options, - \item any user-specified axis limits like |xmin| and |xmax|. - \end{itemize} - - The output coordinate transformation |x coord inv trafo| is applied to tick positions just before evaluating the |xticklabel| and |yticklabel| keys. The tick label code may use additional macros defined by the inverse transformation. - - Remark: \PGFPlots\ will continue to produce tick positions as usual, no extra magic is applied. It may be necessary to provide tick positions explicitly if the default doesn't respect the coordinate space properly. - - The initial value of these keys is -\begin{codeexample}[code only] -\pgfplotsset{ - x coord trafo/.code={}, - x coord inv trafo/.code={}} -\end{codeexample} - \noindent which simply disables the transformation (the same for $y$, of course). -\end{pgfplotsxycodekeylist} - -\subsubsection{Dates as Input Coordinates} -\label{pgfplots:sec:date:coords} -The already mentioned application of using dates as input coordinates has been predefined. It relies on the \pgfname\ calendar library which converts dates to numbers in the julian calendar. Then, one coordinate unit is one day. - -\begin{tikzlibrary}{dateplot} - Loads the coordinate transformation code. -\end{tikzlibrary} - -\begin{stylekey}{/pgfplots/date coordinates in=\mchoice{x,y}} - Installs |x coord trafo| and |x coord inv trafo| (or the respective $y$ variant) such that ISO dates of the form \meta{year}-\meta{month}-\meta{day} are accepted. For example, |2006-02-28| will be converted to an ``appropriate'' integer using the julian calender. - - The result of the transformation are numbers where one unit is one day. - - The transformation is realized using the \pgfname-calendar module, see \cite[Calendar Library]{tikz}. This reference also contains more information about extended syntax options. - - The inverse transformation provides the following three macros which are available during tick label evaluation: - \begin{itemize} - \item |\year| expands to the year component, - \item |\month| expands to the month component, - \item |\day| expands to the day component. - \end{itemize} - This allows to use |\day.\month.\year| inside of |xticklabel|, for example. - - A complete example (with fictional data) is shown below. -\pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}} -% \usetikzlibrary{dateplot}\usepackage{eurosym} -\begin{codeexample}[] -% requires \usetikzlibrary{dateplot} ! - -\pgfplotstabletypeset[string type]{plotdata/accounts.dat} - -\begin{tikzpicture} - \begin{axis}[ - date coordinates in=x, - xticklabel={\day.\month.}, - xlabel={2008}, - stack plots=y, - yticklabel={\pgfmathprintnumber{\tick}\EUR{}}, % <- requires \usepackage{eurosym} - ylabel=Total credit, - ylabel style={yshift=10pt}, - legend style={ - at={(0.5,-0.3)},anchor=north,legend columns=-1}] - - \addplot table[x=date,y=account1] {plotdata/accounts.dat}; - \addplot table[x=date,y=account2] {plotdata/accounts.dat}; - \addplot table[x=date,y=account3] {plotdata/accounts.dat}; - \legend{Giro,Tagesgeld,Sparbuch} - \end{axis} -\end{tikzpicture} -\end{codeexample} -\end{stylekey} - -\begin{pgfplotskey}{date ZERO=\meta{year}-\meta{month}-\meta{day} (initially 2006-01-01)} - A technical key which defines the $0$ coordinate of |date coordinates in|. Users will never see the resulting numbers, so one probably never needs to change it. However, the resulting numbers may become very large and a mantisse of 6 significant digits may not be enough to get accurate results. In this case, |date ZERO| should be set to a number which falls into the input date range. -\end{pgfplotskey} - - - - -\subsection{Miscellaneous Options} - -\begin{pgfplotskey}{disablelogfilter=\mchoice{true,false} (initally false, default true)} -Disables numerical evaluation of $\log(x)$ in \TeX. If you specify this option, any plot coordinates and tick positions must be provided as $\log(x)$ instead of $x$. This may be faster and -- possibly -- more accurate than the numerical log. The current implementation of $\log(x)$ normalizes~$x$ to $m\cdot 10^e$ and computes -\[ \log(x) = \log(m) + e \log(10) \] -where $y = \log(m)$ is computed with a newton method applied to $\exp(y) - m$. The normalization involves string parsing without \TeX-registers. You can savely evaluate $\log(1\cdot 10^{-7})$ although \TeX-registers would produce an underflow for such small numbers. -\end{pgfplotskey} - -\label{sec:disabledatascaling}% -\begin{pgfplotskey}{disabledatascaling=\mchoice{true,false} (initally false, default true)} -\index{Accuracy!Data Transformation}% -\index{Errors!dimension too large}% -Disables internal re-scaling of input data. Normally, every input data like plot coordinates, tick positions or whatever, are parsed without using \TeX's limited number precision. Then, a transformation like - \[ T(x) = 10^{q-m} \cdot x - a \] -is applied to every input coordinate/position where $m$ is ``the order of $x$'' base~$10$. Example: $x=1234 = 1.234\cdot 10^3$ has order~$m=4$ while $x=0.001234 = 1.234\cdot 10^{-3}$ has order $m=-2$. The parameter~$q$ is the order of the axis' width/height. - -The \textbf{effect} of the transformation is that your plot coordinates can be of \emph{arbitrary magnitude} like $0.0000001$ and $0.0000004$. For these two coordinates, \PGFPlots\ will use 100pt and 400pt internally. The transformation is quit fast since it relies only on period shifts. This scaling allows precision beyond \TeX's capabilities. -%\footnote{Please note that while plot coordinates can be of quite large magnitude like $10^12$ or $10^{-9}$, \PGFPlots\ still uses \TeX-registers internally (the math parser of \PGF). If your axis interval is $[1234567.8, 1234567.9]$ or something like that, }. - -The option ``|disabledatascaling|'' disables this data transformation. This has two consequences: first, coordinate expressions like \parg{{\normalfont\texttt{axis cs:}}x,y} have the same effect like \parg{x,y}, no re-scaling is applied. Second, coordinates are restricted to what \TeX\ can handle\footnote{Please note that the axis' scaling requires to compute $1/( x_\text{max} - x_{\text{min}} )$. The option |disabledatascaling| may lead to overflow or underflow in this context, so use it with care! Normally, the data scale transformation avoids this problem.}. - -So far, the data scale transformation applies only to normal axis (logarithmic scales do not need it). -\end{pgfplotskey} - - -\begin{pgfplotsxycodekeylist}{\x\ filter} -The code keys |x filter| and |y filter| allow coordinate filtering. A coordinate filter gets an input coordinate as |#1|, applies some operation and writes the result into the macro |\pgfmathresult|. If |\pgfmathresult| is empty afterwards, the coordinate is discarded. - -It is allowed if filters do not change |\pgfmathresult|. In this case, the unfiltered coordinate will be used. - -Coordinate filters are useful in automatic processing system, where \PGFPlots\ is used to display automatically generated plots. You may not want to filter your coordinates by hand, so these options provide a tool to do this automatically. - -The following filter adds $0.5$ to every $x$ coordinate. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[x filter/.code= - {\pgfmathadd{#1}{0.5}}] -\addplot coordinates { - (4,0) - (6,1) -}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -Please refer to~\cite[pgfmath manual]{tikz} for details about the math engine of \PGF. Please keep in mind that the math engine works with limited \TeX\ precision. - -During evaluation of the filter, the macro |\coordindex| contains the number of the current coordinate (starting with~$0$). Thus, the following filter discards all coordinates after the $5$th and before the $10$th. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - samples=20, - x filter/.code={ - \ifnum\coordindex>4\relax - \ifnum\coordindex<11\relax - \def\pgfmathresult{} - \fi - \fi - }] -\addplot {x^2}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -There is also a style key which simplifies selection by index, see below. - - \PGFPlots\ invokes the filter with argument |#1| set to the input coordinate. For $x$-filters, this is the $x$-coordinate as it is specified to |\addplot|, for $y$-filters it is the $y$-coordinate. - - If the corresponding axis is logarithmic, |#1| is the \emph{logarithm} of the coordinate as a real number, for example |#1=4.2341|. - - The arguments to coordinate filters are not transformed. You may need to call coordinate parsing routines. -\end{pgfplotsxycodekeylist} - -\begin{stylekey}{/pgfplots/skip coords between index=\marg{begin}\marg{end}} - A style which appends an |x filter| which discards selected coordinates. The selection is done by index where indexing starts with~$0$, see |\coordindex|. Every coordinate with index $\meta{begin} \le i < \meta{end}$ will be skipped. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis}[ - samples=20, - skip coords between index={5}{11}, - skip coords between index={15}{18}] - -\addplot {x^2}; -\end{axis} -\end{tikzpicture} -\end{codeexample} -\end{stylekey} - -\begin{pgfplotskey}{filter discard warning=\mchoice{true,false} (initially true)} - Issues a notification in your logfile whenever coordinate filters discard coordinates. -\end{pgfplotskey} - -\begin{pgfplotskey}{execute at begin plot=\marg{commands}} -This axis option allows to invoke \marg{commands} at the beginning of each |\addplot| command. The argument \marg{commands} can be any \TeX\ content. - -You may use this in conjunction with |x filter=...| to reset any counters or whatever. An example would be to change every $4$th coordinate. -\end{pgfplotskey} - -\begin{pgfplotskey}{execute at end plot=\marg{commands}} -This axis option allows to invoke \marg{commands} after each |\addplot| command. The argument \marg{commands} can be any \TeX\ content. -\end{pgfplotskey} - -\begin{pgfplotskey}{forget plot=\marg{true,false} (initially false)} -\label{pgfplots:forgetplot} - Allows to include plots which are not remembered for legend entries, which do not increase the number of plots and which are not considered for cycle lists. - - A forgotten plot can be some sort of decoration which has a separate style and does not influence the axis state, although it is processed as any other plot. - Please provide this option as \meta{behavior option} to |\addplot| as in the following example. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{loglogaxis}[ - table/x=Basis, - table/y={L2/r}, - xlabel=Degrees of Freedom, - ylabel=relative Error, - title=New Experiments (old in gray), - legend entries={$e_1$,$e_2$,$e_3$} - ] - \addplot[black!15] plot[forget plot] - table {plotdata/oldexperiment1.dat}; - \addplot[black!15] plot[forget plot] - table {plotdata/oldexperiment2.dat}; - \addplot[black!15] plot[forget plot] - table {plotdata/oldexperiment3.dat}; - \addplot table {plotdata/newexperiment1.dat}; - \addplot table {plotdata/newexperiment2.dat}; - \addplot table {plotdata/newexperiment3.dat}; - \end{loglogaxis} -\end{tikzpicture} -\end{codeexample} - Since forgotten plots won't increase the plot index, they will use the same |cycle list| entry as following plots. This can be used to ``interrupt'' plots as is described in section~\ref{pgfplots:interrupt}. -\index{Interrupted Plots} - - The style |every forget plot| can be used to configure styles for each such plot. Please note that |every plot no |\meta{index} styles are not applicable here. - - A forgotten plot will be stacked normally if |stack plots| is enabled! -\end{pgfplotskey} - -\begin{pgfplotscodekey}{before end axis} -Allows to insert \marg{commands} just before the axis is ended. This option takes effect inside of the clipped area. -\begin{codeexample}[] -\pgfplotsset{every axis/.append style={ - before end axis/.code={ - \fill[red] (axis cs:1,10) circle(5pt); - \node at (axis cs:-4,10) - {\large This text has been inserted - using \texttt{before end axis}.}; - }}} -\begin{tikzpicture} - \begin{axis} - \addplot {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotscodekey} - -\begin{pgfplotscodekey}{after end axis} -Allows to insert \marg{commands} right after the end of the clipped drawing commands. While |befor end axis| has the same effect as if \marg{commands} had been placed inside of your axis, |after end axis| allows to access axis coordinates without being clipped. -\begin{codeexample}[] -\pgfplotsset{every axis/.append style={ - after end axis/.code={ - \fill[red] (axis cs:1,10) circle(5pt); - \node at (axis cs:-4,10) - {\large This text has been inserted using \texttt{after end axis}.}; - }}} -\begin{tikzpicture} - \begin{axis} - \addplot {x^2}; - \end{axis} -\end{tikzpicture} -\end{codeexample} -\end{pgfplotscodekey} - -\begin{pgfplotskey}{clip marker paths=\mchoice{true,false} (initially false)} - The initial choice |clip marker paths=false| causes markers to be drawn \emph{after} the clipped region. Only their positions will be clipped. As a consequence, markers will be drawn completely, or not at all. The value |clip marker paths=true| is here for backwards compatibility: it does not introduce special marker treatment, so markers may be drawn partially if they are close to the clipping boundary\footnote{Please note that clipped marker paths may be slightly faster during \TeX\ compilation.}. -\end{pgfplotskey} - -\begin{pgfplotskey}{clip=\mchoice{true,false} (initially true)} - Whether any paths inside an axis shall be clipped. -\end{pgfplotskey} - -\begin{pgfplotskey}{axis on top=\mchoice{true,false} (initially false)} - If set to |true|, axis lines, ticks, tick labels and grid lines will be drawn on top of plot graphics. -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - axis on top=true, - axis x line=middle, - axis y line=middle] - \addplot+[fill] {x^3} \closedcycle; - \end{axis} -\end{tikzpicture} -\end{codeexample} - -\begin{codeexample}[] -\begin{tikzpicture} - \begin{axis}[ - axis on top=false, - axis x line=middle, - axis y line=middle] - \addplot+[fill] {x^3} \closedcycle; - \end{axis} -\end{tikzpicture} -\end{codeexample} -Please note that this feature does not affect plot marks. I think it looks unfamiliar if plot marks are crossed by axis descriptions. -\end{pgfplotskey} - -\begin{key}{/pgf/fpu=\marg{true,false} (initially true)} -\index{Precision} - This key activates or deactivates the floating point unit. If it is disabled (|false|), the core \PGF\ math engine written by Mark Wibrow and Till Tantau will be used for |plot expression|. - However, this engine has been written to produce graphics and is not suitable for scientific computing. It is limited to fixed point numbers in the range $\pm 16384.00000$. - - If the |fpu| is enabled (|true|, the initial configuration) the high-precision floating point library of \PGF\ written by Christian Feuersänger will be used. It offers the full range of IEEE double precision computing in \TeX. This FPU is also part of \PGFPlotstable, and it is activated by default for |create col/expr| and all other predefined mathematical methods. - - Use -\begin{codeexample}[code only] -\pgfkeys{/pgf/fpu=false} -\end{codeexample} - \noindent in order to de-activate the extended precision. If you prefer using the |fp| (fixed point) package, possibly combined with Mark Wibrows corresponding \PGF\ library, the |fpu| will be deactivated automatically. Please note, however, that |fp| has a smaller data range (about $\pm 10^{17}$) and may be slower. -\end{key} +\section{The Reference} + +\input pgfplots.reference.axis-addplot.tex +\input pgfplots.reference.preliminaryoptions.tex +\input pgfplots.reference.2dplots.tex +\input pgfplots.reference.3dplots.tex +\input pgfplots.reference.markers-meta.tex +\input pgfplots.reference.axisdescription.tex +\input pgfplots.reference.scaling.tex +\input pgfplots.reference.3dconfiguration.tex +\input pgfplots.reference.errorbars.tex +\input pgfplots.reference.numberformatting.tex +\input pgfplots.reference.specifyrange.tex +\input pgfplots.reference.tickoptions.tex +\input pgfplots.reference.gridoptions-axiscoordinates.tex +\input pgfplots.reference.styleoptions.tex +\input pgfplots.reference.alignment.tex +\input pgfplots.reference.closingplots.tex +\input pgfplots.reference.symbolic-transformations.tex +\input pgfplots.reference.coordfiltering.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 new file mode 100644 index 00000000000..e08329345da --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tickoptions.tex @@ -0,0 +1,772 @@ + + +\subsection{Tick Options} + +\subsubsection{Tick Coordinates and Label Texts} +\begin{pgfplotsxykey}{\x tick=\mchoice{\textbackslash empty,data,\normalfont\marg{coordinate list}} (initially \marg{})} +These options assign a list of \emph{Positions} where ticks shall be placed. The argument is either the empty string (which is the initial value), the command |\empty|, |data| or a list of coordinates. The initial configuration of an empty string means to generate these positions automatically. The choice |\empty| will result in no tick at all. The special value |data| will produce tick marks at every coordinate of the first plot. Otherwise, tick marks will be placed at every coordinate in \marg{coordinate list}. + +The \marg{coordinate list} will be used inside of a |\foreach \x in |\marg{coordinate list} statement. The format is as follows: +\begin{itemize} + \item |{0,1,2,5,8,1e1,1.5e1}| (a series of coordinates), + \item |{0,...,5}| (the same as |{0,1,2,3,4,5}|), + \item |{0,2,...,10}| (the same as |{0,2,4,6,8,10}|), + \item |{9,...,3.5}| (the same as |{9, 8, 7, 6, 5, 4}|), + \item See \cite[Section~34]{tikz} for a more detailed definition of the options. + \item Please be careful with whitespaces inside of \marg{coordinate list} (at least around the dots). +\end{itemize} +For logplots, \PGFPlots\ will apply $\log(\cdot)$ to each element in `\marg{coordinate list}'. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[xtick={12,9897,1468864}] + % see above for this macro: + \plotcoords + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xtick=\empty, + ytick={-2,0.3,3,3.7,4.5}] +\addplot+[smooth] coordinates { + (-2,3) (-1.5,2) (-0.3,-0.2) + (1,1.2) (2,2) (3,5)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\paragraph{Attention:} You can't use the `|...|' syntax if the elements are too large for \TeX! For example, `|xtick=1.5e5,2e7,3e8|' will work (because the elements are interpreted as strings, not as numbers), but `|xtick=1.5,3e5,...,1e10|' will fail because it involves real number arithmetics beyond \TeX's capacities. +\vspace*{0.3cm} + +\noindent +The default choice for tick \emph{positions} in normal plots is to place a tick at each coordinate~$i\cdot h$. The step size~$h$ depends on the axis scaling and the axis limits. It is chosen from a list a ``feasable'' step sizes such that neither too much nor too few ticks will be generated. The default for logplots is to place ticks at positions $10^i$ in the axis' range. The positions depend on the axis scaling and the dimensions of the picture. If log plots contain just one (or two) positions $10^i$ in their limits, ticks will be placed at positions $10^{i\cdot h}$ with ``feasable'' step sizes $h$ as in the case of linear axis. + +\noindent +The tick \emph{appearance} can be (re-)configured with +\begin{codeexample}[code only] +\pgfplotsset{tick style={very thin,gray}}% modifies the style `every tick' +\pgfplotsset{minor tick style={black}} % modifies the style `every minor tick' +\end{codeexample} + +These style commands can be used at any time. The tick line width can be configured with `|major tick length|' and `|minor tick length|'. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[xtick=data,xmajorgrids] + \addplot coordinates { + (1,2) + (2,5) + (4,6.5) + (6,8) + (10,9) + }; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{loglogaxis}[ + title=A log plot with small axis range] + + \addplot coordinates { + (10,1e-4) + (17,8.3176e-05) + (25,7.0794e-05) + (50,5e-5) + }; +\end{loglogaxis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykey} + +\begin{pgfplotsxykeylist}{minor \x\ tick num=\marg{number} (initially 0),minor tick num=\marg{number}} + Sets the number of minor tick lines used either for single axes or for all of them. + + Minor ticks will be disabled if the major ticks don't have the same distance and they are currently only available for linear axes (not for logarithmic ones). + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[minor tick num=1] + \addplot {x^3}; + \addplot {-20*x}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[minor tick num=3] + \addplot {x^3}; + \addplot {-20*x}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[minor x tick num=1, + minor y tick num=3] + \addplot {x^3}; + \addplot {-20*x}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykey}{extra \x\ ticks=\marg{coordinate list}} +Adds \emph{additional} tick positions and tick labels to the $x$~or~$y$ axis. `Additional' tick positions do not affect the normal tick placement algorithms, they are drawn after the normal ticks. This has two benefits: first, you can add single, important tick positions without disabling the default tick label generation and second, you can draw tick labels `on top' of others, possibly using different style flags. + + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xmin=0,xmax=3,ymin=0,ymax=15, + extra y ticks={2.71828}, + extra y tick labels={$e$}, + extra x ticks={2.2}, + extra x tick style={grid=major, + tick label style={ + rotate=90,anchor=east}}, + extra x tick labels={Cut}, +] + \addplot {exp(x)}; + \addlegendentry{$e^x$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\message{Overfull hbox is ok.}% +\begin{codeexample}[] +\pgfplotsset{every axis/.append style={width=5.3cm}} +\begin{tikzpicture} +\begin{loglogaxis}[ + title=Explicitly Provided Limits, + xtickten={1,2}, + ytickten={-5,-6}] +\addplot coordinates + {(10,1e-5) (20,5e-6) (40,2.5e-6)}; +\end{loglogaxis} +\end{tikzpicture} + +\begin{tikzpicture} +\begin{loglogaxis}[ + title=With Extra Ticks, + xtickten={1,2}, + ytickten={-5,-6}, + extra x ticks={20,40}, + extra y ticks={5e-6,2.5e-6}] +\addplot coordinates + {(10,1e-5) (20,5e-6) (40,2.5e-6)}; +\end{loglogaxis} +\end{tikzpicture} + +\begin{tikzpicture} +\begin{loglogaxis}[ + title=With Extra Ticks; $10^e$ format, + extra tick style={log identify minor tick positions=false}, + xtickten={1,2}, + ytickten={-5,-6}, + extra x ticks={20,40}, + extra y ticks={5e-6,2.5e-6}] +\addplot coordinates + {(10,1e-5) (20,5e-6) (40,2.5e-6)}; +\end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + +Remarks: +\begin{itemize} +\item Use |extra x ticks| to highlight special tick positions. The use of |extra x ticks| does not affect minor tick/grid line generation, so you can place extra ticks at positions $j\cdot 10^i$ in log--plots. +\item Extra ticks are always typeset as major ticks. + +They are affected by |major tick length| or options like |grid=major|. +\item Use the style |every extra x tick| (|every extra y tick|) to configure the appearance. +\item You can also use `|extra x tick style=|\marg{...}' which has the same effect. +\end{itemize} +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{\x tickten=\marg{exponent base 10 list}} +These options allow to place ticks at selected positions $10^k, k \in \text{\marg{exponent base 10 list}}$. They are only used for logplots. The syntax for \marg{exponent base 10 list} is the same as above for |xtick=|\marg{list} or |ytick=|\marg{list}. + +Using `|xtickten={1,2,3,4}|' is equivalent to `|xtick={1e1,1e2,1e3,1e4}|', but it requires fewer computational time and it allows to use the short syntax `|xtickten={1,...,4}|'. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{semilogyaxis}[ + samples=8, + ytickten={-6,-4,...,4}, + domain=0:10] + +\addplot {2^(-2*x + 6)}; +\addlegendentry{$2^{-2x + 6}$} + +% or invoke gnuplot to generate coordinates: +\addplot gnuplot[id=pow2] + {2**(-1.5*x -3)}; +\addlegendentry{$2^{-1.5x -3}$} +\end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} + +In case |log basis x|$\neq 10$, the meaning of |xtickten| changes. In such a case, |xtickten| will still assign the exponent, but for the chosen |log basis x| instead of base $10$. +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{\x ticklabels=\marg{label list}} +\label{pgfplots:key:xticklabels}% +Assigns a \emph{list} of tick \emph{labels} to each tick position. Tick \emph{positions} are assigned using the |xtick| and |ytick|-options. + +This is one of two options to assign tick labels directly. The other option is |xticklabel=|\marg{command} (or |yticklabel=|\marg{command}). +The option `|xticklabel|' offers higher flexibility while `|xticklabels|' is easier to use. See also the variant |xticklabels from table|. + +The argument \marg{label list} has the same format as for ticks, that means +\begin{codeexample}[code only] +xticklabels={$\frac{1}{2}$,$e$} +\end{codeexample} +Denotes the two--element--list $\{\frac 12, e\}$. The list indices match the indices of the tick positions. If you need commas inside of list elements, use +\begin{codeexample}[code only] +xticklabels={{0,5}, $e$}. +\end{codeexample} + + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xtick={-1.5,-1,...,1.5}, + xticklabels={% + $-1\frac 12$, + $-1$, + $-\frac 12$, + $0$, + $\frac 12$, + $1$} +] +\addplot[smooth,blue,mark=*] +coordinates { + (-1, 1) + (-0.75, 0.5625) + (-0.5, 0.25) + (-0.25, 0.0625) + (0, 0) + (0.25, 0.0625) + (0.5, 0.25) + (0.75, 0.5625) + (1, 1) +}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{semilogyaxis}[ + ytickten={-2,-1,0,1,2}, + yticklabels={$\frac{1}{100}$,% + $\frac{1}{10}$,% + 1,10,100}, +] + \addplot {exp(x)}; +\end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykey} + + +\begin{pgfplotsxykey}{\x ticklabel=\marg{command}} +These keys change the \TeX-command which creates the tick \emph{labels} assigned to each tick position (see options |xtick| and |ytick|). + +This is one of the two options to assign tick labels directly. The other option is `|xticklabels=|\marg{label list}' (or |yticklabels=|\marg{label list}). The option `|xticklabel|' offers higher flexibility while `|xticklabels|' is easier to use. + +The argument \marg{command} can be any \TeX-text. The following commands are valid inside of \marg{command}: +\begin{description} + \item[] \declareandlabel{\tick} The current element of option |xtick| (or |ytick|). + \item[] \declareandlabel{\ticknum} The current tick number, starting with~0 (it is a macro containing a number). + \item[] \declareandlabel{\nexttick} This command is only valid in case if the |x tick label as interval| option is set (or the corresponding variable for~$y$). It will contain the position of the next tick position, that means the right boundary of the tick interval. +\end{description} +The default argument is +\begin{itemize} + \item \declareandlabel{\axisdefaultticklabel} for normal plots: +\begin{codeexample}[code only] +\def\axisdefaultticklabel{$\pgfmathprintnumber{\tick}$} +\end{codeexample} + + \item \declareandlabel{\axisdefaultticklabellog} for logplots: +\begin{codeexample}[code only] +\def\axisdefaultticklabellog{% + \pgfkeysgetvalue{/pgfplots/log number format code/.@cmd}\pgfplots@log@label@style + \expandafter\pgfplots@log@label@style\tick\pgfeov +} +\end{codeexample} +\end{itemize} +That means you can configure the appearance of linear axis with the number formatting options described in section~\ref{sec:number:printing} and logarithmic axis with |log number format code|, see below. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{semilogyaxis}[ + yticklabel style={/pgf/number format/fixed}, + % changes tick labels to a number instead + % of exponential notation: + yticklabel={% + \pgfmathfloatparsenumber{\tick}% + \pgfmathfloatexp{\pgfmathresult}% + \pgfmathprintnumber{\pgfmathresult}% + }, + ] + \addplot {exp(x)}; + \end{semilogyaxis} +\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|. +\begin{codeexample}[width=4cm] +\begin{tikzpicture} +\begin{axis}[ + title=A special Prewavelet, + xtick={0,1,0.5,0.25,0.75}, + xticklabels={$0$,$1$,$\frac12$,$\frac14$,$\frac34$}, + ytick=data, + ymajorgrids, + yticklabel={% + \scriptsize + \ifdim\tick pt<0pt % a TeX \if -- see TeX Book + \pgfmathparse{-10*\tick}% + $-\pgfmathprintnumber{\pgfmathresult}/10$% + \else + \pgfmathparse{10*\tick}% + $\pgfmathprintnumber{\pgfmathresult}/10$% + \fi + } + ] + \addplot coordinates {(0,-1.2) (0.25,1.1) + (0.5,-0.6) (0.75,0.1) (1,0)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +You can change the appearance of tick labels with +\begin{codeexample}[code only] +\pgfplotsset{tick label style={ + font=\tiny, + /pgf/number format/sci}}% this modifies the `every tick label' style +\end{codeexample} +and/or +\begin{codeexample}[code only] +\pgfplotsset{x tick label style={ + above, + /pgf/number format/fixed zerofill}}% this modifies the `every x tick label' style +\end{codeexample} +and +\begin{codeexample}[code only] +\pgfplotsset{y tick label style={font=\bfseries}}% modifies `every y tick label' +\end{codeexample} +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{\x ticklabels from table=\marg{\textbackslash table or filename}\marg{colname}} + A variant of |xticklabels=|\marg{list} which uses each entry in the column named \meta{colname} from a table as tick labels. + + The first argument \meta{\textbackslash table or filename} can be either a loaded table macro (i.e.\ the result of |\pgfplotstableread|\marg{file name}\marg{\textbackslash table}) or just a file name. + + The second argument can be a column name, a column alias or a |create on use| specification (see \PGFPlotstable\ for the latter two). Furthermore, it can be |[index]|\meta{integer} in which case \meta{integer} is a column index. + + The behavior of |xticklabels from table| is the same as if the column \meta{colname} would have been provided as comma separated list to |xticklabels|. This means the column can contain text, \TeX\ macros or even math mode. + + If you have white spaces in your cells, enclose the complete cell in curly braces, |{example cell}|. The detailed input format for tables is discussed in \verbpdfref{\addplot table} and in the documentation for \PGFPlotstable. +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{extra \x\ tick label=\marg{\TeX\ code}} + As |xticklabel| provides code to generate tick labels for each |xtick|, the key |extra x tick label| provides code to generate tick labels for every element in |extra x ticks|. +\end{pgfplotsxykey} + +\begin{pgfplotsxykey}{extra \x\ tick labels=\marg{label list}} + As |xticklabels| provides explicit tick labels for each |xtick|, the key |extra x tick labels| provides explicit tick labels for every element in |extra x ticks|. +\end{pgfplotsxykey} + + + +\begin{pgfplotsxykey}{\x\ tick label as interval=\mchoice{true,false} (initially false)} +\label{key:pgfplots:ticklabelasinterval} + Allows to treat tick labels as intervals; that means the tick positions denote the interval boundaries. If there are $n$ positions, $(n-1)$ tick labels will be generated, one for each interval. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[x tick label as interval] + \addplot {3*x}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + This mode enables the use of |\nexttick| inside of |xticklabel| (or |yticklabel|). A common application might be a bar plot. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + ybar interval=0.9, + x tick label as interval, + xmin=2003,xmax=2030, + ymin=0,ymax=140, + xticklabel={ + $\pgfmathprintnumber{\tick}$ + -- $\pgfmathprintnumber{\nexttick}$}, + xtick=data, + x tick label style={ + rotate=90,anchor=east, + /pgf/number format/1000 sep=} +] + + \addplot[draw=blue,fill=blue!40!white] + coordinates + {(2003,40) (2005,100) (2006,15) + (2010,90) (2020,120) (2030,3)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykey} + + + +\begin{pgfplotsxykeylist}{\x minorticks=\mchoice{true,false} (initially true),\x majorticks=\mchoice{true,false} (initially true),ticks=\mchoice{minor,major,both,none} (initially both)} +Enables/disables the small tick lines either for single axis or for all of them. Major ticks are those placed at the tick positions and minor ticks are between tick positions. Please note that minor ticks are automatically disabled if |xtick| is not a uniform range\footnote{A uniform list means the difference between all elements is the same for linear axis or, for logarithmic axes, $\log(10)$.}. + +The key |minor tick length=|\marg{dimen} configures the tick length for minor ticks while the |major| variant applies to major ticks. +You can configure the appearance using the following styles: +\begin{codeexample}[code only] +\pgfplotsset{every tick/.append style={color=black}} % applies to major and minor ticks, +\pgfplotsset{every minor tick/.append style={thin}} % applies only to minor ticks, +\pgfplotsset{every major tick/.append style={thick}} % applies only to major ticks. +\end{codeexample} +There is also the style ``|every tick|'' which applies to both, major and minor ticks. +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord}, \x tickmax=\marg{coord}} + These keys can be used to modify minimum/maximum values before ticks are drawn. Because this applies to axis discontinuities, it is described on page~\pageref{key:xytickminmax} under section~\ref{key:xytickminmax}, ``Axis Discontinuities"'. +\end{pgfplotsxykeylist} + +\subsubsection{Tick Alignment: Positions and Shifts} + +\begin{pgfplotsxykeylist}{\x tick pos=\mchoice{left,right,both} (initially both),tick pos=\mchoice{left,right,both}} +Allows to choose where to place the small tick lines. In the default configuration, this does also affect tick \emph{labels}, see below. The |tick pos| style sets all of them to the same value (aliased by |tickpos|\pgfmanualpdflabel{/pgfplots/tickpos}). This option is only useful for boxed axes. + +For $x$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $y$. + +Changing |tick pos| will also affect the placement of tick labels. + +Note that it can also affect |axis lines| key although not all combinations make sense. Make sure the settings are consistent. +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykeylist}{% + \x ticklabel pos=\mchoice{left,right,default} (initially default), + ticklabel pos=\mchoice{left,right,default} (initially default)} +Allows to choose where to place tick \emph{labels}. The choices |left| and |right| place tick labels either at the left or at the right side of the complete axis. The choice |default| uses the same setting as |xtick pos| (or |ytick pos|). This option is only useful for boxed axes -- keep it to |default| for non-boxed figures. The |ticklabel pos| style sets all three of them to the same value. + +For $x$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $x$. +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykeylist}{% + \x tick align=\mchoice{inside,center,outside} (initially inside), + tick align=\mchoice{inside,center,outside} (initially inside)} +Allows to change the location of the ticks relative to the axis lines. The |tick align| sets all of them to the same value. +Default is ``|inside|''. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xtick=data,ytick=data, + xtick align=center] +\addplot coordinates + {(-3,0) (-2,0.1) (-1,-0.6) + (0,1) + (1,-0.6) (2,0.1) (3,0)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xtick=data,ytick=data, + ytick align=outside] +\addplot coordinates + {(-3,0) (-2,0.1) (-1,-0.6) + (0,1) + (1,-0.6) (2,0.1) (3,0)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +These tick alignment options are set automatically by the |axis x line| and |axis y line| methods (unless one appends an asterisk `|*|'): +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + xtick=data, + axis x line=center, + xticklabels={,,}, + ytick={-0.6,0,0.1,1}, + yticklabels={ + $-\frac{6}{10}$,, + $\frac{1}{10}$,$1$}, + ymajorgrids, + axis y line=left, + enlargelimits=0.05] +\addplot coordinates + {(-3,0) (-2,0.1) (-1,-0.6) + (0,1) + (1,-0.6) (2,0.1) (3,0)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykeylist}{% + \x ticklabel shift=\marg{dimension} (initially empty),% + ticklabel shift=\marg{dimension} (initially empty)} + Shifts tick labels in direction of the outer unit normal of the axis by an amount of \marg{dimension}. The |ticklabel shift| sets the same value for all axes. + + This is usually unnecessary as the |anchor| of a tick label already yields enough spacing in most cases. +\end{pgfplotsxykeylist} + +\subsubsection{Tick Scaling - Common Factors In Ticks} +\label{sec:scaled:ticks}% +\begin{pgfplotsxykeylist}{ + scaled ticks=\mchoice{true,false,base 10:{\normalfont\meta{e}},real:{\normalfont\meta{num}},manual:{\normalfont\marg{label}\marg{code}}} (initially true),% + scaled \x\ ticks=\meta{one of the values} (initially true)% +} +Allows to factor out common exponents in tick labels for \emph{linear axes}. For example, if you have tick labels $20000,40000$ and $60000$, you may want to save some space and write $2,4,6$ with a separate factor `$\cdot 10^4$'. Use `|scaled ticks=true|' to enable this feature. In case |true|, tick scaling will be triggered if the data range is either too large or too small (see below). +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[scaled ticks=true] + \addplot coordinates { + (20000,0.0005) + (40000,0.0010) + (60000,0.0020) + }; +\end{axis} +\end{tikzpicture}% +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[scaled ticks=false] + \addplot coordinates { + (20000,0.0005) + (40000,0.0010) + (60000,0.0020) + }; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + The |scaled ticks| key is a style which simply sets scaled ticks for both, $x$ and $y$. + + The value |base 10:|\meta{e} allows to adjust the algorithm manually. For example, |base 10:3| will divide every tick label by $10^3$: +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[scaled ticks=base 10:3, + /pgf/number format/sci subscript] + \addplot coordinates + {(-0.00001,2e12) (-0.00005,4e12) }; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent Here, the \texttt{sci subscript} option simply saves space. +In general, |base 10:|$e$ will divide every tick by $10^e$. The effect +is not limited by the ``too large or too small'' decisions mentioned +above. + + The value |real:|\meta{num} allows to divide every tick by a fixed \meta{num}. + For example, the following plot is physically ranged from $0$ to $2\pi$, but the tick scaling algorithm is configured to divide every tick label by $\pi$. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + xtick={0,1.5708,...,10}, + domain=0:2*pi, + scaled x ticks={real:3.1415}, + xtick scale label code/.code={$\cdot \pi$}] + \addplot {sin(deg(x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + \noindent Setting |scaled ticks=real:|\meta{num} also changes the |tick scale label code| to +\begin{codeexample}[code only] +\pgfkeys{/pgfplots/xtick scale label code/.code= + {$\pgfkeysvalueof{/pgfplots/tick scale binop} \pgfmathprintnumber{#1}$}}. +\end{codeexample} +\noindent The key |tick scale binop| is described below, it is set initially to |\cdot|. + +A further -- not very useful -- example is shown below. Every $x$ tick label has been divided by $2$, every $y$ tick label by $3$. +\nobreak +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + scaled x ticks=real:2, + scaled y ticks=real:3] + \addplot {x^3}; + \node[pin=135:{$(3,9)$}] at (axis cs:3,9) {}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Unfortunately, \meta{num} can't be evaluated with \PGF's math parser (yet) to maintain the full data range accepted by \PGFPlots. + + The last option, |scaled ticks=manual:|\marg{label}\marg{code} allows even more customization. It allows \emph{full control} over the displayed scaling label \emph{and} the scaling code: \marg{text} is used as-is inside of the tick scaling label while \marg{code} is supposed to be a one-argument-macro which scales each tick. Example: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + % warning: the '%' signs are necessary (?) + scaled y ticks=manual:{$+65\,535$}{% + \pgfmathfloatcreate{1}{6.5535}{4}% + \pgfmathfloatsubtract{#1}{\pgfmathresult}% + }, + yticklabel style={ + /pgf/number format/fixed, + /pgf/number format/precision=1}, +] +\addplot coordinates { + (0, 65535) + (13, 65535) + (14, 65536) + (15, 65537) + (30, 65537) +}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent The example uses |$+65\,535$| as tick scale label content. Furthermore, it defines the customized tick label formula $y - (+6.5535\cdot 10^4) = y - 65535$ to generate $y$ tick labels. + +The \marg{text} can be arbitrary. It is completely in user control. The second argument, \marg{code} is supposed to be a one-argument-macro in which |#1| is the current tick position in floating point representation. The macro is expected to assign |\pgfmathresult| (also in floating point representation). The \PGF\ manual~\cite{tikz} contains detailed documentation about its math engine (including floating point\footnote{However, that particular stuff is newer than \PGF\ $2.00$. At the time of this writing, it is only available as (public) CVS version.}). + +This feature may also be used do transform coordinates in case they can't be processed with \PGFPlots: transform them and supply a proper tick scaling method such that tick labels represent the original range. + +If \marg{text} is empty, the tick scale label won't be drawn (and no space will be occupied). + +Tick scaling does \emph{not} work for logarithmic axes. +\end{pgfplotsxykeylist} + +\begin{pgfplotsxycodekeylist}{\x tick scale label code} +Allows to change the default code for scaled tick labels. The default is +\begin{codeexample}[code only] +\pgfplotsset{ + xtick scale label code/.code={$\cdot 10^{#1}$} +} +\end{codeexample} + +More precisely, it is +\begin{codeexample}[code only] +\pgfplotsset{ + xtick scale label code/.code={$\pgfkeysvalueof{/pgfplots/tick scale binop} 10^{#1}$} +} +\end{codeexample} +\noindent and the initial value of |tick scale binop| is |\cdot|, but it can be changed to |\times| if desired. + +If the code is empty, no tick scale label will be drawn (and no space is consumed). +\end{pgfplotsxycodekeylist} + +\begin{pgfplotscodekey}{tick scale label code} + A style which sets |xtick scale label code| and those for $y$ and $z$. +\end{pgfplotscodekey} + + +\begin{pgfplotskey}{tick scale binop=\marg{\TeX\ math operator} (initially \textbackslash cdot)} + Sets the binary operator used to display tick scale labels. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title=\texttt{tick scale + binop=\textbackslash cdot}] +\addplot + [mark=none,blue,samples=250, + domain=0:5] + {exp(10*x)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title=\texttt{tick scale + binop=\textbackslash times}, + tick scale binop=\times] +\addplot + [mark=none,blue,samples=250, + domain=0:5] + {exp(10*x)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + +\begin{pgfplotskey}{scale ticks below=\marg{exponent}} +Allows fine tuning of the `|scaled ticks|' algorithm: if the axis limits are of magnitude $10^e$ and $e<$\marg{exponent}, the common prefactor~$10^e$ will be factored out. The default is +\makeatletter +\pgfplots@scale@ticks@below@exponent +\makeatother. +\end{pgfplotskey} + +\begin{pgfplotskey}{scale ticks above=\marg{exponent}} +Allows fine tuning of the '|scaled ticks|' algorithm: if the axis limits are of magnitude $10^e$ and $e>$\marg{exponent}, the common prefactor~$10^e$ will be factored out. The default is +\makeatletter +\pgfplots@scale@ticks@above@exponent +\makeatother. +\end{pgfplotskey} + + +\subsubsection{Tick Fine Tuning} +The tick placement algorithm depends on a number of parameters which can be tuned to get better results. +\begin{pgfplotskey}{max space between ticks=\marg{number} (initially 35)} +\label{maxspacebetweenticks} + Configures the maximum space between adjacent ticks in full points. The suffix ``|pt|'' has to be omitted and fractional numbers are not supported. The default is~\axisdefaulttickwidth. +\end{pgfplotskey} + +\begin{pgfplotskey}{try min ticks=\marg{number} (initially 3)} + Configures a loose lower bound on the number of ticks. It should be considered as a suggestion, not a tight limit. The default is~\axisdefaulttryminticks. This number will increase the number of ticks if `|max space between ticks|' produces too few of them. + + The total number of ticks may still vary because not all fractional numbers in the axis' range are valid tick positions. +\end{pgfplotskey} + +\begin{pgfplotskey}{try min ticks log=\marg{number} (initially 3)} + The same as |try min ticks|, but for logarithmic axis. +\end{pgfplotskey} + +\begin{pgfplotskeylist}{tickwidth=\marg{dimension} (initially 0.15cm),major tick length=\marg{dimension} (initially 0.15cm)} + Sets the width of major tick lines. +\end{pgfplotskeylist} + +\begin{pgfplotskeylist}{subtickwidth=\marg{dimension} (initially 0.1cm),minor tick length=\marg{dimension} (initially 0.1cm)} + Sets the width of minor tick lines. +\end{pgfplotskeylist} + +\begin{pgfplotsxykeylist}{\x tick placement tolerance (initially 0.05pt)} + Tick lines and labels will be placed if they are no more than this tolerance beyond the axis limits. This threshold should be chosen such that it does not produce visible differences while still providing fault tolerance. + + The threshold is given in paper units of the final figure. +\end{pgfplotsxykeylist} + +\begin{pgfplotsxykey}{log basis \x=\marg{number} (initially empty)} + Allows to change the logarithms used for logarithmic axes. + + Changing to a different log basis is nothing but a scale. However, it also changes the way tick labels are displayed: they will also be shown in the new basis. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{semilogyaxis}[log basis y=2,grid=major,samples at={-4,...,4}] + \addplot {2^x}; + \end{semilogyaxis} +\end{tikzpicture} +~ +\begin{tikzpicture} + \begin{semilogyaxis}[log basis y=10,samples at={-4,...,4}] + \addplot {2^x}; + \end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} + + The initial setting is `|log basis x=|' which defaults to: the natural logarithm for any coordinates (basis $\exp(1)$), and the logarithm base $10$ for the display of tick labels. + + If the log basis is changed to something different than the empty string, the chosen logarithm will be applied to any input coordinate (if the axis scale is log as well) and tick labels will be displayed in this basis. + + In other words: usually, you see log axes base $10$ and that's it. It is only interesting for coordinate filters: + the initial setting (with empty \meta{number}) uses coordinate lists basis $e$ although the display will use basis~$10$ (i.e.\ it is rescaled). Any non-empty value \meta{number} causes both, coordinate lists \emph{and} display to use \meta{number} as basis for the logarithm. The javascript code of the |clickable| library will always use the \emph{display} basis (which is usally $10$) when it computes slopes. + + \paragraph{Technical remarks.} When |log basis x| is used, the style |log basis ticks=|\marg{axis char} will be installed (in this case |log basis ticks=x|). This style in turn will change |log number format code|. + + Please note that |xtickten| will be used differently now: it will provide the desired ticks in the new basis! Despite the misleading name ``|ten|'', |xtickten={1,2,3,4}| will yield ticks at $2^1,2^2,2^3,2^4$ if |log basis x=2| has been set. +\end{pgfplotsxykey} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex index d915a4f8a1a..194e82d6aa4 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.resources.tex @@ -1,8 +1,9 @@ \section{Memory and Speed considerations} +\subsection{Memory Limits of \TeX} \label{sec:pgfplots:optimization} \PGFPlots\ can typeset plots with several thousand points if memory limits of \TeX\ are configured properly. Its runtime is roughly proportional to the number of input points\footnote{In fact, the runtime is pseudo--linear: starting with about $100{,}000$ points, it will become quadratic. This limitation applies to the path length of \PGF\ paths as well. Furthermore, the linear runtime is not possible yet for stacked plots.}. -\message{ATTENTION: I am now about to typeset really huge pictures. You will need to ENLARGE YOUR TeX MEMORY CAPACITIES if this fails...}% +\pgfplotsexpensiveexample \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[ @@ -19,6 +20,7 @@ \end{tikzpicture} \end{codeexample} +\pgfplotsexpensiveexample \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[ @@ -26,27 +28,47 @@ title=Ornstein-Uhlenbeck sample ($13000$ time steps), xlabel=$t$] -\addplot[blue] file{plotdata/ou.dat}; + +\addplot[blue] file {plotdata/ou.dat}; \end{axis} \end{tikzpicture} \end{codeexample} -\message{ok, passed.}% \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. -\subsection{Memory limitations} -The default settings of most \TeX-distributions are quite restrictive, so it may be necessary to adjust them. For Mik\TeX, this can be done using simple command line switches: +\subsection{Memory Limitations} +The default settings of most \TeX-distributions are quite restrictive, so it may be necessary to adjust them. + +Usually, the log--file or the final error message contains a summary about the used ressources, giving a hint which parameter needs to be increased. + +\subsubsection{Mik\TeX} +For Mik\TeX, memory limits can be increased in two ways. The first is to use command line switches: \begin{codeexample}[code only] pdflatex --stack-size=n --save-size=n --main-memory=n --extra-mem-top=n --extra-mem-bot=n --pool-size=n --max-strings=n \end{codeexample} -\noindent Experiment with these settings if Mik\TeX\ runs out of memory. +\noindent Experiment with these settings if Mik\TeX\ runs out of memory. Usually, one doesn't invoke |pdflatex| manually: there is a development aid which does all the invocations, so this one needs to be adjusted. + +Sometimes it might be better to adjust the Mik\TeX\ configuration file permanently, for example to avoid reconfiguring the \TeX\ development program. This can be realized using the command +\begin{codeexample}[code only] +initexmf --edit-config-file=pdflatex +\end{codeexample} +\noindent which can be typed either on a command prompt in Windows or using Start $\gg$ Execute. As a result, an editor will be opened with the correct config file. A sample config file could be +\begin{codeexample}[code only] +main_memory=90000000 +save_size=80000 +\end{codeexample} +or any of the config file entries which are listed below can be entered. +Thanks to ``LeSpocky'' for his documentation in -Usually, the log--file contains a summary about the used ressources, giving a hint which parameter needs to be increased. For Unix installations, one needs to adjust config files. This can be done as follows: +\url{http://blog.antiblau.de/2009/04/21/speicherlimits-von-miktex-erhoehen}. + +\subsubsection{\TeX Live or similar installations} +For Unix installations, one needs to adjust config files. This can be done as follows: \begin{enumerate} \item Locate |texmf.cnf| on your system. On my Ubuntu installation, it is in @@ -72,4 +94,42 @@ stack_size = n \end{codeexample} The log--file usually contains information about the parameter which needs to be enlarged. \end{enumerate} +An example of this config file thing is shown below. It changes memory limits. +\begin{enumerate} + \item Create the file |~/texmf/mytexcnf/texmf.cnf| (and possibly the paths as well). +\begin{codeexample}[code only] +% newly created file ~/texmf/mytexcnf/texmf.cnf: +% If you want to change some of these sizes only for a certain TeX +% variant, the usual dot notation works, e.g., +% main_memory.hugetex = 20000000 +main_memory = 230000000 % 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. +save_size = 150000 % for saving values outside current group +stack_size = 150000 % simultaneous input sources + +% Max number of characters in all strings, including all error messages, +% help texts, font names, control sequences. These values apply to TeX and MP. +%pool_size = 1250000 +% Minimum pool space after TeX/MP's own strings; must be at least +% 25000 less than pool_size, but doesn't need to be nearly that large. +%string_vacancies = 90000 +% Maximum number of strings. +%max_strings = 100000 +% min pool space left after loading .fmt +%pool_free = 47500 +\end{codeexample} + \item Run |texhash| such that \TeX\ updates its |~/texmf/ls-R| database. + \item Create the environment variable |TEXMFCNF| and assign the value `|~/texmf/mytexcnf:|' (including the trailing `|:|'!). For my linux system, this can be done using by adding +\begin{codeexample}[code only] +export TEXMFCNF=~/texmf/mytexcnf: +\end{codeexample} + to |~/.bashrc|. +\end{enumerate} + Unfortunately, \TeX\ does not allow arbitrary memory limits, there is an upper bound hard coded in the executables. + +\subsection{Reducing Typesetting Time} +\PGFPlots\ does a lot of computations ranging from abstract coordinate computations to low level |.pdf| drawing commands (realized by \PGF). For complex plots, this may take a considerable time -- especially for 3D plots. + +One possibility to reduce typesetting time is to tell \PGF\ to generate single, temporary |.pdf| (or |.eps|) documents for a subset (or all) graphics in one run and re-use these temporary images in successive runs. For \PGFPlots, this is the most effective way to reduce typesetting time. It can be accomplished using the |external| library described in section~\ref{sec:pgfplots:export}. diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex index d3caca95ce7..5d1b7fec2a3 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.tex @@ -22,6 +22,8 @@ \input{pgfplots.preamble.tex} %\RequirePackage[german,english,francais]{babel} +\pgfplotsmanualexternalexpensivetrue + %\usetikzlibrary{external} %\tikzexternalize[prefix=figures/]{pgfplots} @@ -30,7 +32,7 @@ {\small Version \pgfplotsversion}\\ {\small\href{http://sourceforge.net/projects/pgfplots}{http://sourceforge.net/projects/pgfplots}}} -%\includeonly{pgfplots.reference} +%\includeonly{pgfplots.libs} \begin{document} @@ -69,36 +71,118 @@ }% \maketitle \begin{abstract}% -\PGFPlots\ draws high--quality function plots in normal or logarithmic scaling with a user-friendly interface directly in \TeX. The user supplies axis labels, legend entries and the plot coordinates for one or more plots and \PGFPlots\ applies axis scaling, computes any logarithms and axis ticks and draws the plots, supporting line plots, piecewise constant plots, bar plots and area plots. It is based on Till Tantau's package \PGF/\Tikz. +\PGFPlots\ draws high--quality function plots in normal or logarithmic scaling with a user-friendly interface directly in \TeX. The user supplies axis labels, legend entries and the plot coordinates for one or more plots and \PGFPlots\ applies axis scaling, computes any logarithms and axis ticks and draws the plots, supporting line plots, scatter plots, piecewise constant plots, bar plots, area plots, mesh-- and surface plots and some more. It is based on Till Tantau's package \PGF/\Tikz. \end{abstract} \tableofcontents \section{Introduction} -This package provides tools to generate plots and labeled axes easily. It draws normal plots, logplots and semi-logplots. Axis ticks, labels, legends (in case of multiple plots) can be added with key-value options. It can cycle through a set of predefined line/marker/color specifications. In summary, its purpose is to simplify the generation of high-quality function plots, especially for use in scientific contexts (logplots). +This package provides tools to generate plots and labeled axes easily. It draws normal plots, logplots and semi-logplots, in two and three dimensions. Axis ticks, labels, legends (in case of multiple plots) can be added with key-value options. It can cycle through a set of predefined line/marker/color specifications. In summary, its purpose is to simplify the generation of high-quality function and/or data plots, and solving the problems of +\begin{itemize} + \item consistency of document and font type and font size, + \item direct use of \TeX\ math mode in axis descriptions, + \item consistency of data and figures (no third party tool necessary), + \item interdocument consistency using preamble configurations and styles. +\end{itemize} +Although not necessary, separate |.pdf| or |.eps| graphics can be generated using the |external| library developed as part of \Tikz. -It is build completely on \Tikz\ and \PGF\ and may be used as \Tikz\ library. +\PGFPlots\ is build completely on \Tikz/\PGF. Knowledge of \Tikz\ will simplify the work with \PGFPlots, although it is not required. \section[About PGFPlots: Preliminaries]{About {\normalfont\PGFPlots}: Preliminaries} This section contains information about upgrades, the team, the installation (in case you need to do it manually) and troubleshooting. You may skip it completely except for the upgrade remarks. +However, note that this library requires at least \PGF\ version $2.00$. At the time of this writing, many \TeX-distributions still contain the older \PGF\ version $1.18$, so it may be necessary to install a recent \PGF\ prior to using \PGFPlots. + +\subsection{Components} +\PGFPlots\ comes with two components: +\begin{enumerate} + \item the plotting component (which you are currently reading) and + \item the \PGFPlotstable\ component which simplifies number formatting and postprocessing of numerical tables. It comes as a separate package and has its own manual \href{file:pgfplotstable.pdf}{pgfplotstable.pdf}. +\end{enumerate} + \subsection{Upgrade remarks} -This release provides a lot of improvements which can be found in all detail in \texttt{ChangeLog} for interested readers. However, some attention is useful with respect to the following changes: +This release provides a lot of improvements which can be found in all detail in \texttt{ChangeLog} for interested readers. However, some attention is useful with respect to the following changes. + +\subsubsection{New Optional Features} \begin{enumerate} - \item Due to a small math bug in \PGF\ $2.00$: you \emph{can't} write `|-x^2|' -- use `|0-x^2|' instead. The same holds for - `|exp(-x^2)|' -- use `|exp(0-x^2)|' instead. + \item \PGFPlots\ 1.3 comes with user interface improvements. The technical distinction between ``behavior options'' and ``style options'' of older versions is no longer necessary (although still fully supported). + + \item \PGFPlots\ 1.3 has a new feature which allows to \emph{move axis labels tight to tick labels} automatically. + + Since this affects the spacing, it is not enabled be default. + + Use +\begin{codeexample}[code only] +\usepackage{pgfplots} +\pgfplotsset{compat=newest} +\end{codeexample} + in your preamble to benefit from the improved spacing\footnote{The |compat=newest| setting is necessary for new features which move axis labels around like reversed axis. However, \PGFPlots\ will still work as it does in earlier versions, your documents will remain the same if you don't set it explicitly.}. + Take a look at the next page for the precise definition of |compat|. + + \item \PGFPlots\ 1.3 now supports reversed axes. It is no longer necessary to use work--arounds with negative units. +\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/,}{}} + + Take a look at the |x dir=reverse| key. + + Existing work--arounds will still function properly. Use |\pgfplotsset{compat=newest}| together with |x dir=reverse| to switch to the new version. +\end{enumerate} + +\subsubsection{Old Features Which May Need Attention} +\begin{enumerate} + \item The |scatter/classes| feature produces proper legends as of version 1.3. This may change the appearance of existing legends of plots with |scatter/classes|. + + \item Due to a small math bug in \PGF\ $2.00$, you \emph{can't} use the math expression `|-x^2|'. It is necessary to use `|0-x^2|' instead. The same holds for + `|exp(-x^2)|'; use `|exp(0-x^2)|' instead. + + This will be fixed with \PGF\ $>2.00$. \item Starting with \PGFPlots\ $1.1$, |\tizkstyle| should \emph{no longer be used} to set \PGFPlots\ options. - Although |\tikzstyle| is still supported for some older \PGFPlots\ options, you should replace any occurance of |\tikzstyle| with |\pgfplotsset{|\meta{style name}|/.style={|\meta{key-value-list}|}}| or the associated |.append style| variant. See section~\ref{sec:styles} for more detail. + Although |\tikzstyle| is still supported for some older \PGFPlots\ options, you should replace any occurance of |\tikzstyle| with |\pgfplotsset{|\meta{style name}|/.style={|\meta{key-value-list}|}}| or the associated |/.append style| variant. See section~\ref{sec:styles} for more detail. \end{enumerate} I apologize for any inconvenience caused by these changes. -This library requires at least \PGF\ version $2.00$. At the time of this writing, many \TeX-distributions still contain the older \PGF\ version $1.18$, so it may be necessary to install a recent \PGF\ prior to using \PGFPlots. +\begin{pgfplotskey}{compat=\mchoice{newest,pre 1.3,default} (initially default)} + The preamble configuration +\begin{codeexample}[code only] +\usepackage{pgfplots} +\pgfplotsset{compat=newest} +\end{codeexample} + allows to choose between backwards compatibility and most recent features. + + \PGFPlots\ version 1.3 comes with new features which may lead to different spacings compared to earlier versions: + \begin{enumerate} + \item Version 1.3 comes with the |xlabel near ticks| feature which places (in this case $x$) axis labels ``near'' the tick labels, taking the size of tick labels into account. + + Older versions used |xlabel absolute|, i.e.\ an absolute distance between the axis and axis labels (now matter how large or small tick labels are). + + The initial setting \emph{keeps backwards compatibility}. + + You are encouraged to use +\begin{codeexample}[code only] +\usepackage{pgfplots} +\pgfplotsset{compat=newest} +\end{codeexample} + in your preamble. + + \item Version 1.3 fixes a bug with |anchor=south west| which occured mainly for reversed axes: the anchors where upside--down. This is fixed now. + + + If you have written some work--around and want to keep it going, use + + |\pgfplotsset{compat/anchors=pre 1.3}|\pgfmanualpdflabel{/pgfplots/compat/anchors}{} + + to disable the bug fix. + \end{enumerate} + + Use |\pgfplotsset{compat=default}| to restore the factory settings. +\end{pgfplotskey} \subsection{The Team} -\PGFPlots\ has been written by Christian Feuersänger and Pascal Wolkotte as a spare time project. We hope it is useful and provides valueable plots. +\PGFPlots\ has been written mainly by Christian Feuersänger with many improvements of Pascal Wolkotte and Nick Papior Andersen as a spare time project. We hope it is useful and provides valueable plots. + +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, author of package |pgfgraph|, who joined development and contributed code for axis lines and tick alignment. Furthermore, I thank Dr.~Schweitzer for many fruitful discussions and Dr.~Meine for his ideas and suggestions. +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. 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. @@ -108,9 +192,12 @@ Last but not least, I thank Till Tantau and Mark Wibrow for their excellent grap \include{pgfplots.libs}% \include{pgfplots.resources}% \include{pgfplots.importexport}% +\include{pgfplots.basic.reference}% \printindex \bibliographystyle{abbrv} %gerapali} %gerabbrv} %gerunsrt.bst} %gerabbrv}% gerplain} +\nocite{pgfplotstable} +\nocite{programmingnotes} \bibliography{pgfplots} \end{document} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsJS.djs b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsJS.djs deleted file mode 100644 index 47c30e2e85f..00000000000 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsJS.djs +++ /dev/null @@ -1,373 +0,0 @@ -\begingroup -\obeyspaces\obeylines\global\let^^M=\jsR% -\catcode`\"=12% -\gdef\dljspgfplotsJSiii{% -/********************************************************************************* - * function sprintf() - written by Kevin van Zonneveld as part of the php to javascript - * conversion project. - * - * More info at: http://kevin.vanzonneveld.net/techblog/article/phpjs_licensing/ - * - * This is version: 1.33 - * php.js is copyright 2008 Kevin van Zonneveld. - * - * Portions copyright Michael White (http://crestidg.com), _argos, Jonas - * Raoni Soares Silva (http://www.jsfromhell.com), Legaev Andrey, Ates Goral - * (http://magnetiq.com), Philip Peterson, Martijn Wieringa, Webtoolkit.info - * (http://www.webtoolkit.info/), Carlos R. L. Rodrigues - * (http://www.jsfromhell.com), Ash Searle (http://hexmen.com/blog/), - * Erkekjetter, GeekFG (http://geekfg.blogspot.com), Johnny Mast - * (http://www.phpvrouwen.nl), marrtins, Alfonso Jimenez - * (http://www.alfonsojimenez.com), Aman Gupta, Arpad Ray - * (mailto:arpad@php.net), Karol Kowalski, Mirek Slugen, Thunder.m, Tyler - * Akins (http://rumkin.com), d3x, mdsjack (http://www.mdsjack.bo.it), Alex, - * Alexander Ermolaev (http://snippets.dzone.com/user/AlexanderErmolaev), - * Allan Jensen (http://www.winternet.no), Andrea Giammarchi - * (http://webreflection.blogspot.com), Arno, Bayron Guevara, Ben Bryan, - * Benjamin Lupton, Brad Touesnard, Brett Zamir, Cagri Ekin, Cord, David, - * David James, DxGx, FGFEmperor, Felix Geisendoerfer - * (http://www.debuggable.com/felix), FremyCompany, Gabriel Paderni, Howard - * Yeend, J A R, Leslie Hoare, Lincoln Ramsay, Luke Godfrey, MeEtc - * (http://yass.meetcweb.com), Mick@el, Nathan, Nick Callen, Ozh, Pedro Tainha - * (http://www.pedrotainha.com), Peter-Paul Koch - * (http://www.quirksmode.org/js/beat.html), Philippe Baumann, Sakimori, - * Sanjoy Roy, Simon Willison (http://simonwillison.net), Steve Clay, Steve - * Hilder, Steven Levithan (http://blog.stevenlevithan.com), T0bsn, Thiago - * Mata (http://thiagomata.blog.com), Tim Wiel, XoraX (http://www.xorax.info), - * Yannoo, baris ozdil, booeyOH, djmix, dptr1988, duncan, echo is bad, gabriel - * paderni, ger, gorthaur, jakes, john (http://www.jd-tech.net), kenneth, - * loonquawl, penutbutterjelly, stensi - * - * Dual licensed under the MIT (MIT-LICENSE.txt) - * and GPL (GPL-LICENSE.txt) licenses. - * - * Permission is hereby granted, free of charge, to any person obtaining a - * copy of this software and associated documentation files (the - * "Software"), to deal in the Software without restriction, including - * without limitation the rights to use, copy, modify, merge, publish, - * distribute, sublicense, and/or sell copies of the Software, and to - * permit persons to whom the Software is furnished to do so, subject to - * the following conditions: - * - * The above copyright notice and this permission notice shall be included - * in all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS - * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. - * IN NO EVENT SHALL KEVIN VAN ZONNEVELD BE LIABLE FOR ANY CLAIM, DAMAGES - * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, - * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - * OTHER DEALINGS IN THE SOFTWARE. - */ -// ATTENTION: this method has been masked such that special characters of TeX and javascript -// don't produce problems. -function sprintf( ) { - // Return a formatted string - // - // + discuss at: http://kevin.vanzonneveld.net/techblog/article/javascript_equivalent_for_phps_sprintf/ - // + version: 804.1712 - // + original by: Ash Searle (http://hexmen.com/blog/) - // + namespaced by: Michael White (http://crestidg.com) - // * example 1: sprintf("\pgfplotsPERCENT01.2f", 123.1); - // * returns 1: 123.10 - - var regex = /\pgfplotsPERCENT\pgfplotsPERCENT\pgfplotsVERTBAR\pgfplotsPERCENT(\d+\$)?([-+\pgfplotsHASH0 ]*)(\*\d+\$\pgfplotsVERTBAR\*\pgfplotsVERTBAR\d+)?(\.(\*\d+\$\pgfplotsVERTBAR\*\pgfplotsVERTBAR\d+))?([scboxXuidfegEG])/g; - var a = arguments, i = 0, format = a[i++]; - - // pad() - var pad = function(str, len, chr, leftJustify) { - var padding = (str.length >= len) ? '' : Array(1 + len - str.length >>> 0).join(chr); - return leftJustify ? str + padding : padding + str; - }; - - // justify() - var justify = function(value, prefix, leftJustify, minWidth, zeroPad) { - var diff = minWidth - value.length; - if (diff > 0) { - if (leftJustify \pgfplotsVERTBAR\pgfplotsVERTBAR !zeroPad) { - value = pad(value, minWidth, ' ', leftJustify); - } else { - value = value.slice(0, prefix.length) + pad('', diff, '0', true) + value.slice(prefix.length); - } - } - return value; - }; - - // formatBaseX() - var formatBaseX = function(value, base, prefix, leftJustify, minWidth, precision, zeroPad) { - // Note: casts negative numbers to positive ones - var number = value >>> 0; - prefix = prefix && number && {'2': '0b', '8': '0', '16': '0x'}[base] \pgfplotsVERTBAR\pgfplotsVERTBAR ''; - value = prefix + pad(number.toString(base), precision \pgfplotsVERTBAR\pgfplotsVERTBAR 0, '0', false); - return justify(value, prefix, leftJustify, minWidth, zeroPad); - }; - - // formatString() - var formatString = function(value, leftJustify, minWidth, precision, zeroPad) { - if (precision != null) { - value = value.slice(0, precision); - } - return justify(value, '', leftJustify, minWidth, zeroPad); - }; - - // finalFormat() - var doFormat = function(substring, valueIndex, flags, minWidth, _, precision, type) { - if (substring == '\pgfplotsPERCENT\pgfplotsPERCENT') return '\pgfplotsPERCENT'; - - // parse flags - var leftJustify = false, positivePrefix = '', zeroPad = false, prefixBaseX = false; - for (var j = 0; flags && j < flags.length; j++) switch (flags.charAt(j)) { - case ' ': positivePrefix = ' '; break; - case '+': positivePrefix = '+'; break; - case '-': leftJustify = true; break; - case '0': zeroPad = true; break; - case '\pgfplotsHASH': prefixBaseX = true; break; - } - - // parameters may be null, undefined, empty-string or real valued - // we want to ignore null, undefined and empty-string values - if (!minWidth) { - minWidth = 0; - } else if (minWidth == '*') { - minWidth = +a[i++]; - } else if (minWidth.charAt(0) == '*') { - minWidth = +a[minWidth.slice(1, -1)]; - } else { - minWidth = +minWidth; - } - - // Note: undocumented perl feature: - if (minWidth < 0) { - minWidth = -minWidth; - leftJustify = true; - } - - if (!isFinite(minWidth)) { - throw new Error('sprintf: (minimum-)width must be finite'); - } - - if (!precision) { - precision = 'fFeE'.indexOf(type) > -1 ? 6 : (type == 'd') ? 0 : void(0); - } else if (precision == '*') { - precision = +a[i++]; - } else if (precision.charAt(0) == '*') { - precision = +a[precision.slice(1, -1)]; - } else { - precision = +precision; - } - - // grab value using valueIndex if required? - var value = valueIndex ? a[valueIndex.slice(0, -1)] : a[i++]; - - switch (type) { - case 's': return formatString(String(value), leftJustify, minWidth, precision, zeroPad); - case 'c': return formatString(String.fromCharCode(+value), leftJustify, minWidth, precision, zeroPad); - case 'b': return formatBaseX(value, 2, prefixBaseX, leftJustify, minWidth, precision, zeroPad); - case 'o': return formatBaseX(value, 8, prefixBaseX, leftJustify, minWidth, precision, zeroPad); - case 'x': return formatBaseX(value, 16, prefixBaseX, leftJustify, minWidth, precision, zeroPad); - case 'X': return formatBaseX(value, 16, prefixBaseX, leftJustify, minWidth, precision, zeroPad).toUpperCase(); - case 'u': return formatBaseX(value, 10, prefixBaseX, leftJustify, minWidth, precision, zeroPad); - case 'i': - case 'd': { - var number = parseInt(+value); - var prefix = number < 0 ? '-' : positivePrefix; - value = prefix + pad(String(Math.abs(number)), precision, '0', false); - return justify(value, prefix, leftJustify, minWidth, zeroPad); - } - case 'e': - case 'E': - case 'f': - case 'F': - case 'g': - case 'G': - { - var number = +value; - var prefix = number < 0 ? '-' : positivePrefix; - var method = ['toExponential', 'toFixed', 'toPrecision']['efg'.indexOf(type.toLowerCase())]; - var textTransform = ['toString', 'toUpperCase']['eEfFgG'.indexOf(type) \pgfplotsPERCENT 2]; - value = prefix + Math.abs(number)[method](precision); - return justify(value, prefix, leftJustify, minWidth, zeroPad)[textTransform](); - } - default: return substring; - } - }; - - return format.replace(regex, doFormat); -} -/*********************************************************************************/ - - -var lastMouseX = -1; -var lastMouseY = -1; -var posOnMouseDownX = -1; -var posOnMouseDownY = -1; - -// preallocation. -var tmpArray1 = new Array(2); -var tmpArray2 = new Array(2); - -/** - * Takes an already existing TextField, changes its value to \c value and places it at (x,y). - * Additional \c displayOpts will be used to format it. - */ -function initTextField( x,y, textField, displayOpts, value ) -{ -textField.value = ""+value; -var R = textField.rect; -R[0] = x; -R[1] = y; -R[2] = R[0] + displayOpts.textSize/2*Math.max( 5,value.length ); -R[3] = R[1] - 1.5*displayOpts.textSize; -textField.rect = R; -textField.textFont = displayOpts.textFont; -textField.textSize = displayOpts.textSize; -textField.fillColor = displayOpts.fillColor;//["RGB",1,1,.855]; -textField.doNotSpellCheck = true; -textField.readonly = true; -if( displayOpts.printable ) -textField.display = display.visible; -else -textField.display = display.noPrint; -} - -/** - * Changes all required Field values of \c plotRegionField, inserts the proper - * value and displays it at the pdf positions (x,y) . - * - * @param plotRegionField a reference to a Field object. - * @param x the x coordinate where the annotation shall be placed and which is used to determine - * the annotation text. - * @param y the corresponding y coord. - * @param axisAnnotObj An object containing axis references. - * @param displayOpts An object for display flags. - * @param[out] retCoords will be filled with the point in axis coordinates. - */ -function placeAnnot( plotRegionField, x,y, textField, axisAnnotObj, displayOpts, retCoords ) -{ -// Get and modify bounding box. The mouse movement is only accurate up to one point -// (mouseX and mouseY are integers), so the bounding box should be an integer as well. -var R = plotRegionField.rect; -R[0] = Math.round(R[0]); -R[1] = Math.round(R[1]); -R[2] = Math.round(R[2]); -R[3] = Math.round(R[3]); -plotRegionField.rect= R; - -var w = R[2] - R[0]; -var h = R[1] - R[3]; - -// compute position 0 <= mx <= 1, 0<= my <= 1 relative to lower(!) left corner. -var mx = x - R[0]; -var my = h - (R[1] - y); - -var unitx = mx / w; -var unity = my / h; - -var realx = axisAnnotObj.xmin + unitx * (axisAnnotObj.xmax - axisAnnotObj.xmin); -var realy = axisAnnotObj.ymin + unity * (axisAnnotObj.ymax - axisAnnotObj.ymin); - -if( retCoords ) { -retCoords[0] = realx; -retCoords[1] = realy; -} - -if( axisAnnotObj.xscale == "log" ) -realx = Math.exp(realx); -if( axisAnnotObj.yscale == "log" ) -realy = Math.exp(realy); - -// console.println( "w = " + w + "; h = " + h ); -// console.println( "mx = " + mx + "; my = " + my ); -// console.println( "unitx = " + unitx + "; unity " + unity ); - -initTextField( x,y, textField, displayOpts, -//util.printf( "(\pgfplotsPERCENT.2f,\pgfplotsPERCENT.2f)", realx,realy ) -sprintf( displayOpts.pointFormat, realx,realy) ); - -} - -/** - * @param formName the name of the clickable button. It is expected to be as large as the underlying plot. - * @param axisAnnotObj an object with the fields - * - xmin, xmax - * - ymin, ymax - * - xscale, yscale - * @param displayOpts an object with the fields - * - pointFormat an sprintf format string to format the final point coordinates. - * The default is "(\pgfplotsPERCENT.2f,\pgfplotsPERCENT.2f)" - * - fillColor the fill color for the annotation. Options are - * transparent, gray, RGB or CMYK color. Default is - * ["RGB",1,1,.855] - * - textFont / textSize - */ -function processAnnotatedPlot(formName, axisAnnotObj, displayOpts, bMouseUp ) -{ -if( !bMouseUp ) { -posOnMouseDownX = mouseX; -posOnMouseDownY = mouseY; -return; -} -var result = this.getField( formName + "-result"); -var result2 = this.getField( formName + "-result2"); -var slope = this.getField( formName + "-slope" ); -if( !result ) { -console.println( "WARNING: there is no TextField \"" + formName + "-result\" to display results for interactive element \"" + formName + "\""); -return; -} -result2.display = display.hidden; -slope.display = display.hidden; - -// clicking twice onto the same point hides it: -if( result.display != display.hidden && -Math.abs(lastMouseX - mouseX) < 5 && -Math.abs(lastMouseY - mouseY) < 5 ) -{ -result.display = display.hidden; -return; -} -lastMouseX = mouseX; -lastMouseY = mouseY; - -var a = this.getField(formName); -if( ! a ) { -console.println( "Warning: there is no form named \"" + formName + "\"" ); -return; -} -if( Math.abs( lastMouseX - posOnMouseDownX ) > 6 \pgfplotsVERTBAR\pgfplotsVERTBAR -Math.abs( lastMouseY - posOnMouseDownY ) > 6 ) -{ -// dragging the mouse results in slope computation: -placeAnnot( a, posOnMouseDownX, posOnMouseDownY, result, axisAnnotObj, displayOpts, tmpArray1 ); -placeAnnot( a, lastMouseX, lastMouseY, result2, axisAnnotObj, displayOpts, tmpArray2 ); - -var m = ( tmpArray2[1] - tmpArray1[1] ) / ( tmpArray2[0] - tmpArray1[0] ); -var n = tmpArray1[1] - m * tmpArray1[0]; - -initTextField( -0.5 * ( lastMouseX + posOnMouseDownX ), -0.5 * ( lastMouseY + posOnMouseDownY ), -slope, -displayOpts, -sprintf( displayOpts.slopeFormat, m, n ) ); - -%-------------------------------------------------- -% var lineobj = this.getAnnot( a.page, formName + '-line' ); -% console.println( 'lineobj = ' + lineobj ); -% lineobj.points = [[lastMouseX,lastMouseY],[posOnMouseDownX,posOnMouseDownY]]; -% lineobj.display = display.visible; -%-------------------------------------------------- - -} else { -placeAnnot( a, lastMouseX, lastMouseY, result, axisAnnotObj, displayOpts, null ); -} -} -}% -\endgroup -\begingroup -\ccpdftex% -\input{dljscc.def}% -\immediate\pdfobj{ << /S /JavaScript /JS (\dljspgfplotsJSiii) >> } -\xdef\objpgfplotsJSiii{\the\pdflastobj\space0 R} -\endgroup -\endinput diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf Binary files differindex 6d7f4d03bdb..9f945031366 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.pdf diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.tex index 83b62a54b5f..9ba0240cc42 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotsexample.tex @@ -1,8 +1,9 @@ \documentclass[a4paper]{article} -% fuer dvipdfm: +% for dvipdfm: %\def\pgfsysdriver{pgfsys-dvipdfm.def} \usepackage{pgfplots} +\pgfplotsset{compat=newest}% <-- moves axis labels near ticklabels (respects tick label widths) \begin{document} \begin{figure} @@ -36,7 +37,7 @@ (4097, 1.20714122e-05) (9217, 3.26101452e-06) }; - \addplot plot coordinates { + \addplot coordinates { (7, 8.47178381e-02) (31, 3.04409349e-02) (111, 1.02214539e-02) diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.dat b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.dat deleted file mode 100644 index c6a2c7ca618..00000000000 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.dat +++ /dev/null @@ -1,11 +0,0 @@ -dof error1 postproc1 -4 2.50000000e-01 {} -16 6.25000000e-02 1.99998 -64 1.56250000e-02 1.99998 -256 3.90625000e-03 1.99998 -1024 9.76562500e-04 1.99998 -4096 2.44140625e-04 1.99998 -16384 6.10351562e-05 1.99998 -65536 1.52587891e-05 1.99998 -262144 3.81469727e-06 1.99998 -1048576 9.53674316e-07 1.99998 diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.html b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.html deleted file mode 100644 index e68495bbbad..00000000000 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.html +++ /dev/null @@ -1,13 +0,0 @@ -<table> -<tr><td>level</td><td>dof</td></tr> -<tr><td>1</td><td>4</td></tr> -<tr><td>2</td><td>16</td></tr> -<tr><td>3</td><td>64</td></tr> -<tr><td>4</td><td>256</td></tr> -<tr><td>5</td><td>1024</td></tr> -<tr><td>6</td><td>4096</td></tr> -<tr><td>7</td><td>16384</td></tr> -<tr><td>8</td><td>65536</td></tr> -<tr><td>9</td><td>262144</td></tr> -<tr><td>10</td><td>1048576</td></tr> -</table> diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.tex deleted file mode 100644 index 127872722ab..00000000000 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example1.out.tex +++ /dev/null @@ -1,13 +0,0 @@ -\begin {tabular}{cc}% -dof&error1\\% -\pgfutilensuremath {4}&\pgfutilensuremath {0.25}\\% -\pgfutilensuremath {16}&\pgfutilensuremath {6.25\cdot 10^{-2}}\\% -\pgfutilensuremath {64}&\pgfutilensuremath {1.56\cdot 10^{-2}}\\% -\pgfutilensuremath {256}&\pgfutilensuremath {3.91\cdot 10^{-3}}\\% -\pgfutilensuremath {1{,}024}&\pgfutilensuremath {9.77\cdot 10^{-4}}\\% -\pgfutilensuremath {4{,}096}&\pgfutilensuremath {2.44\cdot 10^{-4}}\\% -\pgfutilensuremath {16{,}384}&\pgfutilensuremath {6.1\cdot 10^{-5}}\\% -\pgfutilensuremath {65{,}536}&\pgfutilensuremath {1.53\cdot 10^{-5}}\\% -\pgfutilensuremath {2.62\cdot 10^{5}}&\pgfutilensuremath {3.81\cdot 10^{-6}}\\% -\pgfutilensuremath {1.05\cdot 10^{6}}&\pgfutilensuremath {9.54\cdot 10^{-7}}\\% -\end {tabular}% diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example3.dat b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example3.dat new file mode 100644 index 00000000000..b3832fa9922 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example3.dat @@ -0,0 +1,7 @@ +a b c d +0 1 2 3 +4 5 6 7 +8 9 10 11 +12 13 14 15 +16 17 18 19 +20 21 22 23 diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example4.dat b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example4.dat new file mode 100644 index 00000000000..9269a588748 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.example4.dat @@ -0,0 +1,11 @@ +a b +2.000000 8.794 +4.000000 4.397 +8.000000 22.198 +16.000000 1.099 +32.000000 inf +64.000000 12.748 +128.000000 1.374 +256.000000 26.870 +512.000000 inf +1024.000000 1.717 diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf Binary files differindex 3284e7495c1..44298fdc005 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.pdf diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex index 581b033cfcb..15d4668102b 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex @@ -2,7 +2,7 @@ % % Package pgfplots.sty documentation. % -% Copyright 2007/2008 by Christian Feuersaenger. +% Copyright 2007-2009 by Christian Feuersaenger. % % This program is free software: you can redistribute it and/or modify % it under the terms of the GNU General Public License as published by @@ -36,6 +36,35 @@ tabsize=4, } +\makeatletter +\pgfkeys{% + /codeexample/prettyprint/key name with handler/.code 2 args={% + \gdef\pgfplotstablemanualautocheck{}% + \foreach \special in {columns,create on use,alias,display columns}{% + \expandafter\pgfutil@in@\expandafter{\special/}{#1}% + \ifpgfutil@in@ + \xdef\pgfplotstablemanualautocheck{\special}% + \breakforeach + \fi + }% + \ifx\pgfplotstablemanualautocheck\pgfutil@empty% + \pgfmanualpdfref{#1}{#1}/\pgfmanualpdfref{/handlers/#2}{#2}% + \else + \expandafter\def\expandafter\temp\expandafter##\expandafter1\pgfplotstablemanualautocheck/##2\relax{% + \pgfmanualpdfref + {/pgfplots/table/\pgfplotstablemanualautocheck}% + {##1\pgfplotstablemanualautocheck/}% + ##2/% + \pgfmanualpdfref{/handlers/#2}{#2}% + }% + \temp#1\relax + \fi + }, + /pdflinks/search key prefixes in/.add={/pgf/number format/,}{,/pgfplots/table/create col/}, + /pdflinks/show labels=false, +} +\makeatother + %\pgfplotstableset{debug=true} \title{% @@ -80,7 +109,7 @@ It is used with \end{enumerate} Both ways are shown in the examples below. - Knowledge of |pgfkeys| is useful for a deeper insight into this package, as |.style|, |.append style| etc. are specific to |pgfkeys|. Please refer to the \PGF\ manual,~\cite[section pgfkeys]{tikz} if you want a deeper insight into |pgfkeys|. Otherwise, simply skip over to the examples provided in this document. + Knowledge of |pgfkeys| is useful for a deeper insight into this package, as |/.style|, |/.append style| etc. are specific to |pgfkeys|. Please refer to the \PGF\ manual,~\cite[section pgfkeys]{tikz} if you want a deeper insight into |pgfkeys|. Otherwise, simply skip over to the examples provided in this document. You will find key prefixes |/pgfplots/table/| and |/pgf/number format/|. These prefixes can be skipped if they are used in \PGFPlotstable; they belong to the ``default key path'' of |pgfkeys|. \end{command} @@ -121,6 +150,8 @@ There is future support for a second header line which must start with `|$flags \begin{codeexample}[] \pgfplotstableset{% global config, for example in the preamble + % these columns/<colname>/.style={<options>} things define a style + % which applies to <colname> only. columns/dof/.style={int detect,column type=r,column name=\textsc{Dof}}, columns/error1/.style={ sci,sci zerofill,sci sep align,precision=1,sci superscript, @@ -152,7 +183,7 @@ There is future support for a second header line which must start with `|$flags ] {pgfplotstable.example1.dat} \end{codeexample} -\noindent All of these options are explained in the following sections. +\noindent All of these options are explained in all detail in the following sections. Technical note: every opened file will be protocolled into your log file. \end{command} @@ -170,15 +201,12 @@ Technical note: every opened file will be protocolled into your log file. \hspace{2cm} \pgfplotstabletypeset[columns={dof,error2}]\table \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. Technical note: every opened file will be protocolled into your log file. \end{command} -\begin{command}{\pgfplotstablegetrowsof\marg{file name or \textbackslash loadedtable}} - Defines |\pgfmathresult| to be the number of rows in a table. The argument may be either a file name or an already loaded table (the \meta{\textbackslash macro} of |\pgfplotstableread|). -\end{command} - -\begin{key}{/pgfplots/table/col sep=\mchoice{space,comma,semicolon,colon,braces} (initially space)} +\begin{key}{/pgfplots/table/col sep=\mchoice{space,tab,comma,semicolon,colon,braces} (initially space)} Specifies the column separation character for table reading. The initial choice, |space| means ``at least one white space''. White spaces are tab stops or spaces (newlines always delimit lines). For example, the file |pgfplotstable.example1.csv| uses commas as separation characters. @@ -204,20 +232,26 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1) You may call |\pgfplotstableset{col sep=comma}| once in your preamble if all your tables use commas as column separator. Please note that if cell entries (for example column names) contain the separation character, you need to enclose the column entry in \emph{braces}: |{grad(log(dof),log(error2)}|. If you want to use unmatched braces, you need to write a backslash before the brace. For example the name `|column{withbrace|' needs to be written as `|column\{withbrace|'. + + For |col sep|$\neq$|space|, spaces will be considered to be part of the argument (there is no trimming). However, (as usual in \TeX), multiple successive spaces and tabs are summarized into white space. Of course, if |col sep=tab|, tabs are the column separators and will be treated specially. Furthermore, if you need empty cells in case |col sep=space|, you have to provide |{}| to delimit such a cell since |col sep=space| uses \emph{at least} one white space (consuming all following ones). The value |col sep=braces| is special since it actually uses two separation characters. Every single cell entry is delimited by an opening and a closing brace, \marg{entry}, for this choice. Furthermore, any 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.}. \end{key} -\begin{key}{/pgfplots/table/header=\marg{boolean} (initially true)} - Configures if column names shall be identified during input operations. +\begin{key}{/pgfplots/table/header=\mchoice{true,false,has colnames} (initially true)} + Configures if column names shall be identified automatically during input operations. - The `header' is the first non-comment line, but only if this line contains non-numerical entries. If the first non-comment line contains at least one non-numerical entry (for example `|a name|'), each entry in this line is supposed to be a column name. + The first non-comment line \emph{can} be a header which contains column names. The |header| key configures how to detect if that is really the case. + + The choice \declaretext{true} enables auto--detection of column names: If the first non-comment line contains at least one non-numerical entry (for example `|a name|'), each entry in this line is supposed to be a column name. If the first non-comment line contains only numerical data, it is used as data row. In this case, column indices will be assigned as column ``names''. - If the first non-comment line contains only numerical data, it is used as data row. In this case, column indices will be assigned as column ``names''. + The choice \declaretext{false} is identical to this last case, i.e.\ even if the first line contains strings, they won't be recognised as column names. - Use |header=false| to force this last case, i.e. even if the first line contains strings, they won't be recognised as column names. + 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} @@ -228,16 +262,20 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1) \begin{codeexample}[] \pgfplotstabletypeset[columns={dof,level,[index]4}]{pgfplotstable.example1.dat} \end{codeexample} + + The special |pgfkeys| feature |\pgfplotstableset{columns/.add={}{,a further col}}| allows to \emph{append} a value, in this case `|,a further col|' to the actual value. See |/.add| for details. \end{key} \begin{pgfplotstablealiaskey} - Assigns the new name \meta{new col name} for the column denoted by \meta{real col name}. Afterwards, accessing \meta{new col name} will use the data associated with column \meta{real col name}. + 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}. - You can use |columns/|\meta{new col name}|/.style| to assign styles for the alias, not for the original column name. + 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. - In case \meta{new col name} contains characters which are required for key settings, you need to use braces around it: ``|alias/{name=wi/th,special}/.initial={othername}|''. + In case \meta{col name} contains characters which are required for key settings, you need to use braces around it: ``|alias/{name=wi/th,special}/.initial={othername}|''. + + This key is used whenever columns are queries, it applies also to the |\addplot table| statement of \PGFPlots. \end{pgfplotstablealiaskey} \begin{pgfplotstablecolumnkey} @@ -302,7 +340,7 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1) If all column types are empty, the complete argument is skipped (assuming that no |tabular| environment is generated). - Use |\pgfplotstableset{column type/.add=|\marg{before}\marg{after}|}| to \emph{modify} a value instead of overwriting it. The |.add| key handler works for other options as well. + Use |\pgfplotstableset{column type/.add=|\marg{before}\marg{after}|}| to \emph{modify} a value instead of overwriting it. The |/.add| key handler works for other options as well. \begin{codeexample}[narrow] \pgfplotstabletypeset[ columns={dof,error1,info}, @@ -312,6 +350,13 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1) \end{codeexample} \end{key} +\begin{key}{/pgfplots/table/column name=\marg{\TeX\ display column name}} + Sets the column name in the current context. + + It is advisable to provide this option inside of a column-specific style, i.e. using + + |columns/|\marg{lowlevel colname}|/.style={column name=|\marg{\TeX\ display column name}|}| . +\end{key} \begin{codekey}{/pgfplots/table/assign column name} Allows to \emph{modify} the value of |column name|. @@ -334,8 +379,6 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1) The first argument determines the alignment of the header column. - The style |dec sep align| actually introduces two new |tabular| columns\footnote{Unfortunately, \texttt{dec sep align} is currently not very flexible when it comes to column type modifications. In particular, it is not possible to use colored columns or cells in conjunction with \texttt{dec sep align}. The \texttt{\textbackslash rowcolor} command works properly; the color hangover introduced by \texttt{colortbl} is adjusted automatically.}, namely |r@{}l|. It introduces multicolumns for column names accordingly and handles numbers which do not have a decimal separator. - Please note that you need |\usepackage{array}| for this style. \begin{codeexample}[] % requires \usepackage{array} @@ -362,11 +405,60 @@ level,dof,error1,error2,info,{grad(log(dof),log(error2))},quot(error1) ] {pgfplotstable.example1.dat} \end{codeexample} - It may be advisable to use the |zerofill| variants to force at least one digit after the decimal separator. + It may be advisable to use |fixed zerofill| and/or |sci zerofill| to force at least one digit after the decimal separator to improve placement of exponents: +\begin{codeexample}[] +% requires \usepackage{array} +\pgfplotstabletypeset[ + use comma, + columns={dof,error1,error2,info,{grad(log(dof),log(error2))}}, + columns/error1/.style={dec sep align,sci zerofill}, + columns/error2/.style={sci,sci subscript,sci zerofill,dec sep align}, + columns/info/.style={fixed,dec sep align}, + columns/{grad(log(dof),log(error2))}/.style={fixed,dec sep align,fixed zerofill} +] + {pgfplotstable.example1.dat} +\end{codeexample} + + The style |dec sep align| actually introduces two new |tabular| columns\footnote{Unfortunately, \texttt{dec sep align} is currently not very flexible when it comes to column type modifications. In particular, it is not possible to use colored columns or cells in conjunction with \texttt{dec sep align}. The \texttt{\textbackslash rowcolor} command works properly; the color hangover introduced by \texttt{colortbl} is adjusted automatically.}, namely |r@{}l|. It introduces multicolumns for column names accordingly and handles numbers which do not have a decimal separator. + + + Note that for fixed point numbers, it might be an alternative to use |fixed zerofill| combined with |column type=r| to get a similar effect. Please note that this style overwrites |column type|, |assign cell content| and some number formatting settings. \end{stylekey} +%-------------------------------------------------- +% FIXME : doesn't really work as intended: +% \begin{stylekey}{/pgfplots/table/dec sep align/no unbounded} +% Changes the internal processing of |dec sep align| such that unbounded values like $NaN$ and $\pm \infty$ will be aligned in exactly the same way as the column name. +% +% This avoids funny spacing around unbounded coordinates when used with |dec sep align|. + +% NO GALLERY +% \begin{codeexample}[] +% \pgfplotstabletypeset{pgfplotstable.example4.dat} +% \vrule +% +% \pgfplotstabletypeset[ +% columns/b/.style={fixed,precision=1}, +% ] +% {pgfplotstable.example4.dat} +% \vrule +% +% \pgfplotstabletypeset[ +% columns/b/.style={fixed,precision=1,dec sep align}, +% ] +% {pgfplotstable.example4.dat} +% \vrule +% +% \pgfplotstabletypeset[ +% columns/b/.style={fixed,precision=1,dec sep align,dec sep align/no unbounded}, +% ] +% {pgfplotstable.example4.dat} +% \end{codeexample} +% \end{stylekey} +%-------------------------------------------------- + \begin{stylekey}{/pgfplots/table/sci sep align=\marg{header column type} (initially c)} A style which aligns numerical columns at the exponent in scientific representation. @@ -454,6 +546,9 @@ A style which is installed for every column with odd column index (starting with \begin{command}{\pgfplotstablecol} During the evaluation of row or column options, this command expands to the current columns' index. \end{command} +\begin{command}{\pgfplotstablecolname} + During the evaluation of column options, this command expands to the current column's name. It is valid while |\pgfplotstabletypeset| processes the column styles (including the preprocessing step explained in section~\ref{sec:pgfplotstable:preproc}), prepares the output cell content and checks row predicates. +\end{command} \label{pgfplotstable:page:tablerow} \begin{command}{\pgfplotstablerow} During the evaluation of row or column options, this command expands to the current rows' index. @@ -466,6 +561,15 @@ A style which is installed for every column with odd column index (starting with During evaluation of \emph{rows}, this command expands to the total number of \emph{output} rows. \end{command} +\begin{command}{\pgfplotstablename} + During |\pgfplotstabletypeset|, this macro contains the table's macro name as top-level expansion. If you are unfamiliar with ``top-level-expansions'' and `|\expandafter|', you will probably never need this macro. + + Advances users may benefit from expressions like + + |\expandafter\pgfplotstabletypeset\pgfplotstablename|. + + For tables which have been loaded from disk (and have no explicitly assigned macro name), this expands to a temporary macro. +\end{command} \subsection{Configuring Row Appearance} @@ -572,10 +676,12 @@ The following styles allow to configure the final table code \emph{after any cel \begin{key}{/pgfplots/table/begin table=\marg{code} (initially \textbackslash begin\{tabular\})} Contains \marg{code} which is generated as table start. + + Use |begin table/.add={}{[t]}| to append the prefix |[t]|. \end{key} \begin{codekey}{/pgfplots/table/typeset cell} - A code key which assigns |/pgfplots/table/@cell content| to the final output of the current cell. + A code key which assigns \declareandlabel{/pgfplots/table/@cell content} to the final output of the current cell. The first argument, |#1|, is the final cell's value. After this macro, the value of |@cell content| will be written to the output. @@ -587,7 +693,7 @@ The following styles allow to configure the final table code \emph{after any cel \pgfkeyssetvalue{/pgfplots/table/cell content}{#1&}% \fi \end{codeexample} - \paragraph{Attention:} The value of |\pgfplotstablecol| is now in the range $1,\dotsc,n$ where $n=$ |\pgfplotstablecols|. This simplifies checks whether we have the last column. + \paragraph{Attention:} The value of |\pgfplotstablecol| starts with $1$ in this context, i.e.\ it is in the range $1,\dotsc,n$ where $n=$ |\pgfplotstablecols|. This simplifies checks whether we have the last column. \end{codekey} \begin{key}{/pgfplots/table/end table=\marg{code} (initially \textbackslash end\{tabular\})} @@ -615,7 +721,13 @@ The command |\pgfutilensuremath| checks whether math mode is active and switches \begin{codeexample}[code only] \pgfplotstableset{include outfiles} % for example in the document's preamble \end{codeexample} - This allows to place any corrections manually into generated output files. + This allows to place any corrections manually into generated output files since \PGFPlotstable\ won't overwrite the resulting tables automatically. + + This will affect tables for which the |outfile| option is set. If you wish to apply it to every table, consider +\begin{codeexample}[code only] +\pgfplotstableset{every table/.append style={outfile={#1.out}}} +\end{codeexample} + \noindent which will generate an |outfile| name for every table. \end{key} \begin{key}{/pgfplots/table/force remake=\marg{boolean} (initially false)} If enabled, the effect of |include outfiles| is disabled. As all key settings only last until the next brace (or |\end|\meta{}), this key can be used to re-generate some output files while others are still included. @@ -623,6 +735,8 @@ The command |\pgfutilensuremath| checks whether math mode is active and switches \begin{key}{/pgfplots/table/write to macro=\marg{\textbackslash macroname}} If the value of |write to macro| is not empty, the completely generated (tabular) code will be written into the macro \marg{\textbackslash macroname}. + + See the |typeset=false| key in case you need \emph{only} the resulting macro. \end{key} \begin{key}{/pgfplots/table/skip coltypes=\mchoice{true,false} (initially false)} @@ -1089,7 +1203,7 @@ The main idea is to select one typesetting algorithm (for example ``format my nu This first step to typeset a table involves the obvious input operations. Furthermore, the ``new column creation'' operations explained in section~\ref{pgfplotstable:createcol} are processed at this time. The table data is read (or acquired) as already explained earlier in this manual. Then, if columns are missing, column alias and |create on use| specifications will be processed as part of the loading procedure. See section~\ref{pgfplotstable:createcol} for details about column creation. \subsection{Typesetting Cell Content} -Typesetting cells means to take their value and ``do something''. In many cases, this involves number formatting routines. For example, the ``raw'' input data |12.56| might become |1.235| |\cdot| |10^1|. The result of this stage is no longer useful for content-based computations. The typesetting step follows the preprocessing step. +Typesetting cells means to take their value and ``do something''. In many cases, this involves number formatting routines. For example, the ``raw'' input data |12.56| might become |1.26| |\cdot| |10^1|. The result of this stage is no longer useful for content-based computations. The typesetting step follows the preprocessing step. \begin{codekey}{/pgfplots/table/assign cell content} Allows to redefine the algorithm which assigns cell contents. The argument |#1| is the (unformatted) contents of the input table. @@ -1104,13 +1218,13 @@ Typesetting cells means to take their value and ``do something''. In many cases, \end{codekey} \begin{key}{/pgfplots/table/assign cell content as number} - This here is the default implementation of |assign cell contents|. + This here is the default implementation of |assign cell content|. It invokes |\pgfmathprintnumberto| and writes the result into |@cell content|. \end{key} \begin{stylekey}{/pgfplots/table/string type} - A style which redefines |assign cell contents| to simply return the ``raw'' input data, that means as text column. This assumes input tables with valid \LaTeX\ content (verbatim printing is not supported). + 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/date type=\marg{date format}}% (initially \year-\month-\day)} @@ -1121,10 +1235,22 @@ Typesetting cells means to take their value and ``do something''. In many cases, % \usepackage{pgfcalendar} \pgfplotstableset{columns={date,account1}} +% plotdata/accounts.dat contains: +% +% date account1 account2 account3 +% 2008-01-03 60 1200 400 +% 2008-02-06 120 1600 410 +% 2008-03-15 -10 1600 410 +% 2008-04-01 1800 500 410 +% 2008-05-20 2300 500 410 +% 2008-06-15 800 1920 410 + +% Show the contents in `string type': \pgfplotstabletypeset[ columns/date/.style={string type} ]{plotdata/accounts.dat} \hspace{1cm} +% Show the contents in `date type': \pgfplotstabletypeset[ columns/date/.style={date type={\monthname\ \year}} ]{plotdata/accounts.dat} @@ -1167,22 +1293,23 @@ Typesetting cells means to take their value and ``do something''. In many cases, The date feature is implemented using the \PGF\ calendar module. This module employs the package |translator| (if it is loaded). I don't have more detail yet, sorry. Please refer to \cite{tikz} for more details. \subsection{Preprocessing Cell Content} -The preprocessing step allows to change cell contents \emph{before} any typesetting routine (like number formatting) has been applied. The data is available in numerical format and math operations can be applied. Furthermore, cells can be erased depending on their numerical value. The preprocess step follows the data acquisition step (``loading step''). This means in particular that you can create (or copy) columns and apply operations on them. +\label{sec:pgfplotstable:preproc} +The preprocessing step allows to change cell contents \emph{before} any typesetting routine (like number formatting) has been applied. Thus, if tables contain numerical data, it is possible to apply math operations at this stage. Furthermore, cells can be erased depending on their numerical value. The preprocess step follows the data acquisition step (``loading step''). This means in particular that you can create (or copy) columns and apply operations on them. \begin{codekey}{/pgfplots/table/preproc cell content} - Allows to \emph{modify} the contents of cells \emph{before} |assign cell contents| is called. + Allows to \emph{modify} the contents of cells \emph{before} |assign cell content| is called. - The semantics is as follows: before the preprocessor, |@cell content| contains the raw input data (or, maybe, the result of another preprocessor call). After the preprocessor, |@cell content| is filled with a -- possibly modified -- value. The resulting value is then used as input to |assign cell contents|. + The semantics is as follows: before the preprocessor, |@cell content| contains the raw input data (or, maybe, the result of another preprocessor call). After the preprocessor, |@cell content| is filled with a -- possibly modified -- value. The resulting value is then used as input to |assign cell content|. - In the default settings, |assign cell contents| expects numerical input. So, the preprocessor is expected to produce numerical output. + In the default settings, |assign cell content| expects numerical input. So, the preprocessor is expected to produce numerical output. - It is possible to provide multiple preprocessor directives using |.append code| or |.append style| key handlers. + It is possible to provide multiple preprocessor directives using |/.append code| or |/.append style| key handlers. - In case you don't want (or need) stackable preprocessors, you can also use `|#1|' to get the raw input datum as it is found in the file. + In case you don't want (or need) stackable preprocessors, you can also use `|#1|' to get the raw input datum as it is found in the file. Furthermore, the key |@unprocessed cell content| will also contain the raw input datum. \end{codekey} \begin{stylekey}{/pgfplots/table/string replace=\marg{pattern}\marg{replacement}} - Appends code to the current |preproc cell content| value which replace every occurence of \marg{pattern} with \marg{replacement}. No expansion is performed during this step; \marg{pattern} must match literally. + Appends code to the current |preproc cell content| value which replaces every occurence of \marg{pattern} with \marg{replacement}. No expansion is performed during this step; \marg{pattern} must match literally. \begin{codeexample}[] \pgfplotstabletypeset[columns={level,dof}] {pgfplotstable.example1.dat} @@ -1200,6 +1327,40 @@ The preprocessing step allows to change cell contents \emph{before} any typesett Appends code to the current |preproc cell content| value which replaces every infinite number with the empty string. This clears any cells with $\pm \infty$ and NaN. \end{stylekey} +\begin{stylekey}{/pgfplots/table/preproc/expr=\marg{math expression}} + Appends code to the current |preproc cell content| value which evaluates \marg{math expression} for every cell. Arithmetics are carried out in floating point. + + Inside of \marg{math expression}, use one of the following expressions to get the current cell's value. + \begin{itemize} + \item The string `|##1|' expands to the cell's content as it has been found in the input file, ignoring preceeding preprocessors. + + This is usually enough. + + \item The command |\thisrow|\marg{the currently processed column name} expands to the current cell's content. This will also include the results of preceeding preprocessors. + + Note that |\thisrow{}| in this context (inside of the preprocessor) is not as powerful as in the context of column creation routines: the argument must match exactly the name of the currently processed column name. You can also use the shorthand + + |\thisrow{\pgfplotstablecolname}|. + + \item The command |\pgfkeysvalueof{/pgfplots/table/@cell content}| is the same. + \end{itemize} + +\begin{codeexample}[] +\pgfplotstabletypeset[ + columns={level}, + columns/level/.style={ + column name={$2\cdot \text{level}+4$}, + preproc/expr={2*##1 + 4} + } +] + {pgfplotstable.example1.dat} +\end{codeexample} + + Empty cells won't be processed, assuming that a math expression with an ``empty number'' will fail. + + Note that there is also an |create col/expr| which is more powerful than |preproc/expr|. +\end{stylekey} + \begin{stylekey}{/pgfplots/table/multiply with=\marg{real number}} Appends code to the current |preproc cell content| value which multiplies every cell with \marg{real number}. Arithmetics are carried out in floating point. \end{stylekey} @@ -1245,7 +1406,7 @@ The preprocessing step allows to change cell contents \emph{before} any typesett \begin{codekey}{/pgfplots/table/row predicate} A boolean predicate which allows to select particular rows of the input table. The argument |#1| contains the current row's index (starting with~$0$, not counting comment lines or column names). - The return value is assigned to the \TeX-if |\ifpgfplotstableuserow|. If the boolean is not changed, the return value is true. + The return value is assigned to the \TeX-if \declareandlabel{\ifpgfplotstableuserow}. If the boolean is not changed, the return value is true. \begin{codeexample}[narrow] % requires \usepackage{booktabs} \pgfplotstabletypeset[ @@ -1262,7 +1423,7 @@ The preprocessing step allows to change cell contents \emph{before} any typesett ] {pgfplotstable.example1.dat} \end{codeexample} - Please note that |row predicate| is applied \emph{before} any other option which affects row appearance. It is evaluated before |assign cell contents|. For example, the even/odd row styles refer to those rows for which the predicate returns |true|. In fact, you can use |row predicate| to truncate the complete table before it as actually processed. + Please note that |row predicate| is applied \emph{before} any other option which affects row appearance. It is evaluated before |assign cell content|. For example, the even/odd row styles refer to those rows for which the predicate returns |true|. In fact, you can use |row predicate| to truncate the complete table before it as actually processed. During |row predicate|, the macro |\pgfplotstablerows| contains the total number of \emph{input} rows. @@ -1311,34 +1472,60 @@ The preprocessing step allows to change cell contents \emph{before} any typesett If the available number of rows is not dividable by \marg{part count}, the remaining entries are distributed equally among the first parts. \end{stylekey} +\begin{stylekey}{/pgfplots/table/unique=\marg{column name}} + A style which appends an |row predicate| which suppresses successive occurances of the same elements in \marg{column name}. + For example, if \marg{column name} contains |1,1,3,5,5,6,5,0|, the application of |unique| results in |1,3,5,6,5,0| (the last |5| is kept -- it is not directly preceeded by another |5|). + + The algorithm uses string token comparison to find multiple occurances\footnote{To be more precise, the comparison is done using \texttt{\textbackslash ifx}, i.e. cell contents won't be expanded. Only the tokens as they are seen in the input table will be used.}. + + The argument \marg{column name} can be a column name, index, alias, or |create on use| specification (the latter one must not depend on other |create on use| statements). It is not necessary to provide a \marg{column name} which is part of the output. + + However, it \emph{is} necessary that the |unique| predicate can be evaluated for all columns, starting with the first one. That means it is an error to provide |unique| somewhere deep in column--specific styles. +\end{stylekey} \subsection{Postprocessing Cell Content} The postprocessing step is applied after the typesetting stage, that means it can't access the original input data. However, it can apply final formatting instructions which are not content based. \begin{codekey}{/pgfplots/table/postproc cell content} - Allows to \emph{modify} assigned cell content \emph{after} it has been assigned, possibly content-dependend. Ideas could be to draw negative numbers in red, typeset single entries in bold face or insert replacement text. + Allows to \emph{modify} assigned cell content \emph{after} it has been assigned, possibly content-dependent. Ideas could be to draw negative numbers in red, typeset single entries in bold face or insert replacement text. This key is evaluated \emph{after} |assign cell content|. Its semantics is to modify an existing |@cell content| value. - There may be more than one |postproc cell content| command, if you use |.append code| or |.append style| to define them: + There may be more than one |postproc cell content| command, if you use |/.append code| or |/.append style| to define them: \begin{codeexample}[] % requires \usepackage{eurosym} \pgfplotstabletypeset[ column type=r, columns={dof,info}, columns/info/.style={ + % stupid example for multiple postprocessors: postproc cell content/.append style={ - /pgfplots/table/@cell content/.add={$\bf}{$}}, + /pgfplots/table/@cell content/.add={$\bf}{$}, + }, postproc cell content/.append style={ - /pgfplots/table/@cell content/.add={}{\EUR{}}} + /pgfplots/table/@cell content/.add={}{\EUR{}}, + } }] {pgfplotstable.example1.dat} \end{codeexample} - The code above modifies |@cell content| successively. First, ``|$\bf ... $|'' is inserted, then ``|...\EUR|''. It should be noted that |pgfkeys| handles |.style| and |.code| in (quasi) the same way -- both are simple code keys and can be used as such. You can combine both with |.append style| and |.append code|. Please refer to~\cite[section about pgfkeys]{tikz} for details. + The code above modifies |@cell content| in two steps. The net effect is to prepend ``|$\bf |'' and to append ``|$ \EUR|''. It should be noted that |pgfkeys| handles |/.style| and |/.code| in (quasi) the same way -- both are simple code keys and can be used as such. You can combine both with |/.append style| and |/.append code|. Please refer to~\cite[section about pgfkeys]{tikz} for details. + + As in |assign cell content|, the code can evaluate helper macros like |\pgfplotstablerow| to change only particular entries. Furthermore, the postprocessor may depend on the unprocessed cell input (as it has been found in the input file or produced by the loading procedure) and/or the preprocessed cell value. These values are available as + \begin{itemize} + \item the key \declareandlabel{@unprocessed cell content} which stores the raw input, + \item the key \declareandlabel{@preprocessed cell content} which stores the result of the preprocessor, + \item the key \declareandlabel{@cell content} which contains the result of the typesetting routine, + \item the shorthand `|#1|' which is also the unprocessed input argument as it has been found in the input table. + \end{itemize} + Remember that you can access the key values using + + |\pgfkeysvalueof{/pgfplots/table/@preprocessed cell content}| - As in |assign cell contents|, the code can evaluate helper macros like |\pgfplotstablerow| to change only particular entries. Furthermore, the argument ``|#1|'' expands to the \emph{unformatted} input argument which was found in the input table. This allows complete context based formatting options. Please remember that empty strings may appear due to column balancing -- introduce special treatment if necessary. + at any time. + + This allows complete context based formatting options. Please remember that empty strings may appear due to column balancing -- introduce special treatment if necessary. - There is one special case which occurs if |@cell content| itsself contains the cell separation character `|&|'. In this case, |postproc cell contents| is invoked \emph{separately} for each part before and after the ampersand and the ampersand is inserted afterwards. This allows compatibility with special styles which create artificial columns in the output (which is allowed, see |dec sep align|). To allow separate treatment of each part, you can use the macro |\pgfplotstablepartno|. It is defined only during the evaluation of |postproc cell content| and it evaluates to the current part index (starting with~$0$). If there is no ampersand in your text, the value will always be~$0$. + There is one special case which occurs if |@cell content| itsself contains the cell separation character `|&|'. In this case, |postproc cell content| is invoked \emph{separately} for each part before and after the ampersand and the ampersand is inserted afterwards. This allows compatibility with special styles which create artificial columns in the output (which is allowed, see |dec sep align|). To allow separate treatment of each part, you can use the macro \declareandlabel{\pgfplotstablepartno}. It is defined only during the evaluation of |postproc cell content| and it evaluates to the current part index (starting with~$0$). If there is no ampersand in your text, the value will always be~$0$. This key is evaluated inside of a local \TeX\ group, so any local macro assignments will be cleared afterwards. @@ -1370,23 +1557,59 @@ Since this may be useful in a more general context, it is available as |empty ce \end{stylekey} \begin{stylekey}{/pgfplots/table/set content=\marg{content}} - A style which redefines |postproc cell contents| to always return the value \marg{content}. + A style which redefines |postproc cell content| to always return the value \marg{content}. \end{stylekey} +\begin{stylekey}{/pgfplots/table/fonts by sign=\marg{\TeX\ code for positive}\marg{\TeX\ code for negative}} + Appends code to |postproc cell content| which allows to set fonts for positive and negative numbers. + + The arguments \meta{\TeX\ code for positive} and \meta{\TeX\ code for negative} are inserted right before the typesetted cell content. It is permissable to use both ways to change \LaTeX\ fonts: the |\textbf|\marg{argument} or the |{\bfseries |\marg{argument}|}| way. + +% \usepackage{pgfcalendar} +\begin{codeexample}[] +% Requires +% \usepackage{pgfcalendar} + +% plotdata/accounts.dat contains: +% +% date account1 account2 account3 +% 2008-01-03 60 1200 400 +% 2008-02-06 120 1600 410 +% 2008-03-15 -10 1600 410 +% 2008-04-01 1800 500 410 +% 2008-05-20 2300 500 410 +% 2008-06-15 800 1920 410 + +\pgfplotstabletypeset[ + columns={date,account1}, + column type=r, + columns/date/.style={date type={\monthname\ \year}}, + columns/account1/.style={fonts by sign={}{\color{red}}} +] + {plotdata/accounts.dat} +\end{codeexample} + In fact, the arguments for this style don't need to be font changes. The style |fonts by sign| inserts several braces and the matching argument into |@cell content|. To be more precise, it results in + + |{|\meta{\TeX\ code for negative}|{|\meta{cell value}|}}| for negative numbers and + + |{|\meta{\TeX\ code for positive}|{|\meta{cell value}|}}| for all other numbers. +\end{stylekey} \section{Generating Data in New Tables or Columns} \label{pgfplotstable:createcol} It is possible to create new tables from scratch or to change tables after they have been loaded from disk. \subsection{Creating New Tables From Scratch} -\begin{command}{\pgfplotstablenew\oarg{options}\marg{row count}\marg{\textbackslash table}} +\begin{commandlist}{% + \pgfplotstablenew\oarg{options}\marg{row count}\marg{\textbackslash table},% + \pgfplotstablenew*\oarg{options}\marg{row count}\marg{\textbackslash table}} Creates a new table from scratch. - The new table will contain all columns listed in the |columns| key - which needs to be provided in \oarg{options}\footnote{Currently, you need to provide at least one column here: the implementation gets confused for completely empty tables. If you do not provide any column name, a dummy column will be created.}. + The new table will contain all columns listed in the |columns| key. For |\pgfplotstablenew|, the |columns| key needs to be provided in \oarg{options}. For |\pgfplotstablenew*|, the current value of |columns| is used, no matter where and when it has been set. + Furthermore, there must be |create on use| statements (see the next subsection) for every - column which shall be generated. Columns are generated + column which shall be generated\footnote{Currently, you need to provide at least one column: the implementation gets confused for completely empty tables. If you do not provide any column name, a dummy column will be created.}. Columns are generated independently, in the order of appearance in |columns|. The table will contain exactly \marg{row count} rows. If \marg{row count} is an |\pgfplotstablegetrowsof| statement, that statement will be executed and the resulting number of rows be used. Otherwise, \marg{row count} will be evaluated as number. @@ -1412,9 +1635,10 @@ It is possible to create new tables from scratch or to change tables after they % show it: \pgfplotstabletypeset\table \end{codeexample} -\end{command} +\end{commandlist} \begin{command}{\pgfplotstablevertcat\marg{\textbackslash table1}\marg{\textbackslash table2 or filename}} +\label{table:vertcat} Appends the contents of \marg{\textbackslash table2} to \marg{\textbackslash table1} (``vertical cat''). To be more precise, only columns which exist already in \marg{\textbackslash table1} will be appended and every column which exists in \marg{\textbackslash table1} must exist in \marg{\textbackslash table2} (or there must be |alias| or |create on use| specifications to generate them). If the second argument is a file name, that file will be loaded from disk. @@ -1425,6 +1649,21 @@ It is possible to create new tables from scratch or to change tables after they \pgfplotstablevertcat{\output}{datafile2} % appends rows of datafile2 \pgfplotstablevertcat{\output}{datafile3} % appends rows of datafile3 \end{codeexample} + + \paragraph{Remark:} The output table \marg{\textbackslash table1} will be defined in the current \TeX\ scope and it will be erased afterwards. + The current \TeX\ scope is delimited by an extra set of curly braces. However, every \LaTeX\ environment and, unfortunately, the \Tikz\ |\foreach| statement as well, introduce \TeX\ scopes. + + \PGFPlots\ has some some loop statements which do not introduce extra scopes. For example, +\begin{codeexample}[code only] +\pgfplotsforeachungrouped \i in {1,2,...,10} {% + \pgfplotstablevertcat{\output}{datafile\i} % appends `datafile\i' -> `\output' +}% +\end{codeexample} + These looping macros are explained in the manual of \PGFPlots, reference section ``Miscellaneous Commands'' +\end{command} + +\begin{command}{\pgfplotstableclear\marg{\textbackslash table}} + Clears a table. Note that it is much more reliable to introduce extra curly braces `|{ ... }|' around table operations -- these braces define the scope of a variable (including tables). \end{command} \subsection{Creating New Columns From Existing Ones} @@ -1437,8 +1676,8 @@ This command offers a flexible framework to generate new columns. It has been de The following documentation is for all who want to \emph{write} specialised columns. It is not particularly difficult; it is just technical and it requires some knowledge of |pgfkeys|. If you don't like it, you can resort to predefined column generation styles - and enable those styles in \marg{options}. -The column entries will be created using the command key |create col/assign|. It will be invoked for every row of the table. -It is supposed to assign contents to |create col/next content|. +The column entries will be created using the command key \pgfmanualpdflabel{/pgfplots/table/create col/assign}{\declaretext{create col/assign}}. It will be invoked for every row of the table. +It is supposed to assign contents to \pgfmanualpdflabel{/pgfplots/table/create col/next content}{\declaretext{create col/next content}}. During the evaluation, the macro |\thisrow|\marg{col name} expands to the current row's value of the column identified by \marg{col name}. Furthermore, |\nextrow|\marg{col name} expands to the \emph{next} row's @@ -1446,26 +1685,32 @@ value of the designated column and |\prevrow|\marg{col name} expands to the valu So, the idea is to simply redefine the command key |create col/assign| in such a way that it fills new cells as desired. -Two special |assign| routines are available for the first and last row: The contents for the \emph{last} row is computed with |create col/assign last|. Its semantics is the same. The contents for the \emph{first} row is computed with |create col/assign first| to simplify special cases here. These first and last commands are optional, their default is to invoke the normal |assign| routine. +Two special |assign| routines are available for the first and last row: The contents for the \emph{last} row is computed with \pgfmanualpdflabel{/pgfplots/table/create col/assign last}{\declaretext{create col/assign last}}. Its semantics is the same. The contents for the \emph{first} row is computed with \pgfmanualpdflabel{/pgfplots/table/create col/assign first}{\declaretext{create col/assign first}} to simplify special cases here. These first and last commands are optional, their default is to invoke the normal |assign| routine. The evaluation of the |assign| keys is done in local \TeX\ groups (i.e. any local definitions will be cleared afterwards). The following macros are useful during cell assignments: \begin{enumerate} - \item |\prevrow|\marg{col name} / |\getprevrow|\marg{col name}\marg{\textbackslash macro} + \item \declareandlabel{\prevrow}\marg{col name} / \declareandlabel{\getprevrow}\marg{col name}\marg{\textbackslash macro} These two routines return the value stored in the \emph{previous} row of the designated column \marg{col name}. The |get| routine stores it into \meta{\textbackslash macro}. - \item |\thisrow|\marg{col name} / |\getthisrow|\marg{col name}\marg{\textbackslash macro} + The argument \meta{col name} has to denote either an existing column name or one for which an |alias/|\meta{col name} exists. + + \item \declareandlabel{\thisrow}\marg{col name} / \declareandlabel{\getthisrow}\marg{col name}\marg{\textbackslash macro} These two routines return the \emph{current} row's value stored in the designated column. The |get| routine stores it into \meta{\textbackslash macro}. - \item |\nextrow|\marg{col name} / |\getnextrow|\marg{col name}\marg{\textbackslash macro} + The argument \meta{col name} has to denote either an existing column name or one for which an |alias/|\meta{col name} exists. + + \item \declareandlabel{\nextrow}\marg{col name} / \declareandlabel{\getnextrow}\marg{col name}\marg{\textbackslash macro} These two routines return the \emph{next} row's value. + The argument \meta{col name} has to denote either an existing column name or one for which an |alias/|\meta{col name} exists. + \item |\pgfplotstablerow| and |\pgfplotstablerows| which contain the current row's index and the total number of rows, respectively. See page~\pageref{pgfplotstable:page:tablerow} for details. - \item |\pgfmathaccuma| and |\pgfmathaccumb| can be used to transport intermediate results. + \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 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} @@ -1493,7 +1738,9 @@ The following example takes our well-known input table and creates a copy of the There is one more speciality: you can use |columns=|\marg{column list} to reduce the runtime complexity of this command. This works only if the |columns| key is provided directly into \marg{options}. In this case |\thisrow| and its variants are only defined for those columns listed in the |columns| value. -\paragraph{Limitations.} Currently, you can only access three values of one column at a time: the current row, the previous row and the next row. Access to arbitrary indices is not (yet) supported. Furthermore, this command has been designed to modify an existing table. You can't create a table from scratch with this command. +\paragraph{Limitations.} Currently, you can only access three values of one column at a time: the current row, the previous row and the next row. Access to arbitrary indices is not (yet) supported. + +\paragraph{Remark:} If you'd like to create a table from scratch using this command (or the related |create on use| simplification), take a look at |\pgfplotstablenew|. The default implementation of |assign| is to produce empty strings. The default implementation of |assign last| is to invoke |assign|, so in case you never really use the next row's value, you won't need to touch |assign last|. The same holds for |assign first|. \end{command} @@ -1530,6 +1777,8 @@ The default implementation of |assign| is to produce empty strings. The default In case \meta{col name} contains characters which are required for key settings, you need to use braces around it: ``|create on use/{name=wi/th,special}/.style={...}|''. More examples for |create on use| are shown below while discussing the available column creation styles. + + Note that |create on use| is also available within \PGFPlots, in |\addplot table| when used together with the |read completely| key. \end{pgfplotstablecreateonusekey} \subsection{Predefined Column Generation Methods} @@ -1595,13 +1844,13 @@ The following keys can be used in both |\pgfplotstablecreatecol| and the easier \subsubsection{Mathematical Operations} -\begin{key}{/pgf/fpu=\marg{true,false}} +\begin{key}{/pgf/fpu=\mchoice{true,false} (initially true)} \index{Precision} Before we start to describe the column generation methods, one word about the math library. The core is always the \PGF\ math engine written by Mark Wibrow and Till Tantau. However, this engine has been written to produce graphics and is not suitable for scientific computing. I added a high-precision floating point library to \PGF\ which will be part of releases newer than \PGF\ $2.00$. It offers the full range of IEEE double precision computing in \TeX. This FPU is also part of \PGFPlotstable, and it is activated by default for |create col/expr| and all other predefined mathematical methods. - The FPU won't be active for newly defined numerical styles. If you want to add own routines or styles, you will need to use + The FPU won't be active for newly defined numerical styles (although it is active for the predefined mathematical expression parsing styles like |create col/expr|). If you want to add own routines or styles, you will need to use \begin{codeexample}[code only] \pgfkeys{/pgf/fpu=true} \end{codeexample} @@ -1644,7 +1893,8 @@ The following keys can be used in both |\pgfplotstablecreatecol| and the easier create on use/new/.style={ create col/expr={\pgfmathaccuma + \thisrow{level}}}, create on use/new2/.style={ - create col/expr accum={\pgfmathaccuma - \thisrow{level}}{100}} + create col/expr accum={\pgfmathaccuma * \thisrow{level}}{1}%<- start with `1' + } } \pgfplotstabletypeset[ @@ -1763,6 +2013,8 @@ The example creates two columns: the |new| column is just the sum of each value columns={cut}] {2} \table + +% Show the data: \pgfplotstabletypeset{\table} \begin{tikzpicture} @@ -1775,16 +2027,41 @@ The example creates two columns: the |new| column is just the sum of each value \end{loglogaxis} \end{tikzpicture} \end{codeexample} - In the example above, we are searching for $x_1$ and $x_2$ such that $f_1(x_1) = \pgfmathprintnumber{2.5e-4}$ and $f_2(x_2) =\pgfmathprintnumber{2.5e-4}$. On the left is the automatically computed result. On the right is a problem illustration with proper annotation. + In the example above, we are searching for $x_1$ and $x_2$ such that $f_1(x_1) = \pgfmathprintnumber{2.5e-4}$ and $f_2(x_2) =\pgfmathprintnumber{2.5e-4}$. On the left is the automatically computed result. On the right is a problem illustration with proper annotation using \PGFPlots\ to visualize the results. The \marg{cut value} is set to |2.5e-4|. The \marg{common options} contain the problem setup; in our case logarithmic scales and column names. The third argument is a comma-separated-list. Each element $i$ is a set of keys describing how to get $f_i(\cdot)$. - During both, \marg{common options} and the key sets, the following keys can be used: + During both, \marg{common options} and \marg{one key-value set for each plot}, the following keys can be used: \begin{itemize} - \item |table|: either a file name or an already loaded table where to get the data points, - \item |x|: the column name of the $x$ axis, - \item |y|: the column name of the $y$ axis. + \item \declareandlabel{table}|=|\marg{table file or \textbackslash macro}: either a file name or an already loaded table where to get the data points, + \item \declareandlabel{x}|=|\marg{col name}: the column name of the $x$ axis, + \item \declareandlabel{y}|=|\marg{col name}: the column name of the $y$ axis. + \item \declareandlabel{foreach}|=|\marg{\textbackslash foreach loop head}\marg{file name pattern} + This somewhat advanced syntax allows to collect tables in a loop automatically: + +\begin{codeexample}[] +\pgfplotstablenew[ + % same as above... + 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, + foreach={\i in {1,2}}{plotdata/newexperiment\i.dat}}% + {}% just leave this empty. + }, + columns={cut}] + {2} + \table +% Show the data: +\pgfplotstabletypeset{\table} +\end{codeexample} + \PGFPlotstable\ will call |\foreach |\meta{\textbackslash foreach loop head} and it will expand \marg{file name pattern} for every iteration. For every iteration, a simpler list entry of the form + + |table=|\marg{expanded pattern}|,x=|\marg{value of x}|,y=|\marg{value of y} + + will be generated. + + It is also possible to provide |foreach=| inside of \marg{one key-value set for each plot}. The |foreach| key takes precedence over |table|. Details about the accepted syntax of |\foreach| can be found in the \pgfname\ manual. \end{itemize} - The keys |xmode| and |ymode| can take either |log| or |linear|. All mentioned keys have the common key path + The keys \declareandlabel{xmode} and \declareandlabel{ymode} can take either |log| or |linear|. All mentioned keys have the common key path \textcolor{red!75!black}{\texttt{/pgfplots/table/create col/function graph cut/}}. \end{stylekey} @@ -1851,10 +2128,275 @@ Empty cells will be filled with |{}| if |col sep=space|. Use the |empty cells wi In case you want to reset all, you should also consider the key |disable rowcol styles|. \end{key} +\subsection{A summary of how to define and use styles and keys} +This section summarizes features of |pgfkeys|. The complete documentation can be found in the \pgfname\ manual,~\cite{tikz}. +\begin{handler}{{.style}=\marg{key-value-list}} + Defines or redefines a style \meta{key}. A style is a normal key which will set all options in \marg{key-value-list} when it is set. + + Use |\pgfplotstableset{|\meta{key}|/.style={|\meta{key-value-list}|}}| to (re-) define a style \meta{key} in the namespace |/pgfplots/table|. +\end{handler} + +\begin{handler}{{.append style}=\marg{key-value-list}} + Appends \marg{key-value-list} to an already existing style \meta{key}. This is the preferred method to change the predefined styles: if you only append, you maintain compatibility with future versions. + + 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}{{.add}=\marg{before}\marg{after}} + Changes \meta{key} by prepending \meta{before} and appending \meta{after}. +\begin{codeexample}[] +\pgfplotstableset{columns={a column}} +`\pgfkeysvalueof{/pgfplots/table/columns}'; +\pgfplotstableset{columns/.add={}{,another}} +`\pgfkeysvalueof{/pgfplots/table/columns}'; +\pgfplotstableset{columns/.add={}{,and one more}} +`\pgfkeysvalueof{/pgfplots/table/columns}'. +\end{codeexample} + This can be used inside of |\pgfplotsinvokeforeach| or similar (ungrouped!) loop constructs. +\end{handler} + +\begin{handler}{{.code}=\marg{\TeX\ code}} + Occasionally, the \PGFPlots\ user interface offers to replace parts of its routines. This is accomplished using so called ``code keys''. What it means is to replace the original key and its behavior with new \marg{\TeX\ code}. Inside of \marg{\TeX\ code}, any command can be used. Furthermore, the |#1| pattern will be the argument provided to the key. + +\begin{codeexample}[] +\pgfplotsset{ + My Code/.code={This is a pgfkeys feature. Argument=`#1'}} +\pgfplotsset{My Code={is here}} +\end{codeexample} + The example defines a (new) key named |My Code|. Essentially, it is nothing else but a |\newcommand|, plugged into the key-value interface. The second statement ``invokes'' the code key. +\end{handler} + +\begin{handler}{{.append code}=\marg{\TeX\ code}} + Appends \marg{\TeX\ code} to an already existing |/.code| key named \meta{key}. +\end{handler} + + +\begin{handler}{{.code 2 args}=\marg{\TeX\ code}} + As |/.code|, but this handler defines a key which accepts two arguments. When the so defined key is used, the two arguments are available as |#1| and |#2|. +\end{handler} + + \subsection{Plain \TeX\ and Con\TeX t support} \label{sec:pgfplotstable:context} The table code generator is initialised to produce \LaTeX\ |tabular| environments. However, it only relies on~`|&|' being the column separator and~`|\\|' the row terminator. The |column type| feature is more or less specific to |tabular|, but you can disable it completely. Replace |begin table| and |end table| with appropriate \TeX- or Con\TeX t commands to change it. If you have useful default styles (or bug reports), let me know. +\subsection{Basic Level Table Access and Modification} +\PGFPlotstable\ provides several methods to access and manipulate tables at an elementary level. + +Please keep in mind that \PGFPlotstable\ has been written as tool for table visualization. As such, it has been optimized for the case of relatively few rows (although it may have a lot of columns). The runtime for table creation and modification is currently $O(N^2)$ where $N$ is the number of rows\footnote{The runtime for \texttt{plot table} is linear in the number of rows using a special routine.}. This is completely acceptable for tables with few rows because \TeX\ can handle those structures relatively fast. Keep your tables small! \PGFPlotstable\ is \emph{not} a tool for large-scale matrix operations. + +Tables are always stored as a sequence of column vectors. Therefore, iteration over all values in one column is simple whereas iteration over all values in one row is complicated and expensive. + +\begin{command}{\pgfplotstableforeachcolumn\meta{table}\textbackslash as\marg{\textbackslash macro}\marg{code}} + Iterates over every column name of \meta{table}. The \meta{\textbackslash macro} will be set to the currently visited column name. Then, \marg{code} will be executed. During \marg{code}, |\pgfplotstablecol| denotes the current column index (starting with 0). +\begin{codeexample}[] +\begin{minipage}{0.8\linewidth} +\pgfplotstableread{pgfplotstable.example1.dat}\table +\pgfplotstableforeachcolumn\table\as\col{% + column name is `\col'; index is\pgfplotstablecol;\par +} +\end{minipage} +\end{codeexample} + + This routine does not introduce \TeX\ groups, variables inside of \marg{code} are not scoped. +\end{command} + +\begin{command}{\pgfplotstableforeachcolumnelement\meta{column name}\textbackslash of\meta{table}\textbackslash as\meta{\textbackslash cellcontent}\marg{code}} + Reports every table cell $t_{ij}$ for a fixed column $j$ in read-only mode. + + For every cell in the column named \meta{column name}, \marg{code} will be executed. During this invocation, the macro \meta{\textbackslash cellcontent} will contain the cell's content and |\pgfplotstablerow| will contain the current row's index. +\begin{codeexample}[] +\begin{minipage}{0.8\linewidth} +\pgfplotstableread{pgfplotstable.example1.dat}\table +\pgfplotstableforeachcolumnelement{error1}\of\table\as\cell{% + I have now cell element `\cell' at row index `\pgfplotstablerow';\par +} +\end{minipage} +\end{codeexample} + The argument \meta{column name} can also be a column index. In that case, it should contain |[index]|\meta{integer}, for example |[index]4|. Furthermore, column aliases and column which should be generated on-the-fly (see |create on use|) can be used for \meta{column name}. + + This routine does not introduce \TeX\ groups, variables inside of \marg{code} are not scoped. +\end{command} + +\begin{command}{\pgfplotstablemodifyeachcolumnelement\meta{column name}\textbackslash of\meta{table}\textbackslash as\meta{\textbackslash cellcontent}\marg{code}} + A routine which is similar to |\pgfplotstableforeachcolumnelement|, + but any changes of \meta{\textbackslash cellcontent} which might occur during \marg{code} will be written back into the respective cell. + +\begin{codeexample}[] +\pgfplotstableread{pgfplotstable.example1.dat}\table +\pgfplotstablemodifyeachcolumnelement{error1}\of\table\as\cell{% + \edef\cell{\#\pgfplotstablerow: \cell}% +} +\pgfplotstabletypeset[columns=error1,string type]{\table} +\end{codeexample} + + If \marg{column name} is a column alias or has been created on-the-fly, a new column named \meta{column name} will be created. +\end{command} + +\begin{command}{\pgfplotstablegetelem\marg{row}\marg{col}\textbackslash of\meta{table}} + Selects a single table element at row \marg{row} and column \marg{col}. The second argument has the same format as that described in the last paragraph: it should be a column name or a column index (in which case it needs to be written as |[index]|\meta{number}). + + The return value will be written to |\pgfplotsretval|. +\begin{codeexample}[] +\pgfplotstableread{pgfplotstable.example1.dat}{\table} +\pgfplotstablegetelem{4}{error1}\of{\table} +The value (4,error1) is `\pgfplotsretval'. + +\pgfplotstablegetelem{2}{[index]0}\of{\table} +The value (2,0) is `\pgfplotsretval'. +\end{codeexample} + + \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}} + Defines |\pgfmathresult| to be the number of rows in a table. The argument may be either a file name or an already loaded table (the \meta{\textbackslash macro} of |\pgfplotstableread|). +\end{command} + + +\begin{command}{\pgfplotstablevertcat\marg{\textbackslash table1}\marg{\textbackslash table2 or filename}} + See page \pageref{table:vertcat} for details about this command. +\end{command} + +\begin{command}{\pgfplotstablenew\oarg{options}\marg{row count}\marg{\textbackslash table}} + See section~\ref{pgfplotstable:createcol} for details about this command. +\end{command} +\begin{command}{\pgfplotstablecreatecol\oarg{options}\marg{row count}\marg{\textbackslash table}} + See section~\ref{pgfplotstable:createcol} for details about this command. +\end{command} + +\begin{commandlist}{% + \pgfplotstabletranspose\oarg{options}\marg{\textbackslash outtable}\marg{\textbackslash table or filename},% + \pgfplotstabletranspose*\oarg{options}\marg{\textbackslash outtable}\marg{\textbackslash table or filename}}% + Defines \meta{\textbackslash outtable} to be the transposed of \marg{\textbackslash table of filename}. The input argument can be either a file name or an already loaded table. + + The version with `|*|' is only interesting in conjunction with the |columns| option, see below. + +\begin{codeexample}[] +\pgfplotstabletypeset[string type]{pgfplotstable.example3.dat} +\end{codeexample} + +\begin{codeexample}[] +\pgfplotstabletranspose\table{pgfplotstable.example3.dat} +\pgfplotstabletypeset[string type]\table +\end{codeexample} + + The optional argument \meta{options} can contain options which influence the transposition: + \begin{pgfplotskey}{table/colnames from=\marg{colname} (initially empty)} + Inside of |\pgfplotstabletranspose|, this key handles how to define output column names. + + If \marg{colname} \emph{is} empty (the initial value), the output column names will simply be the old row indices, starting with~$0$. + + If \marg{colname} is not empty, it denotes an input column name whose cell values will make up the output column names: +\begin{codeexample}[] +\pgfplotstabletranspose[colnames from=c]\table{pgfplotstable.example3.dat} +\pgfplotstabletypeset[string type]\table +\end{codeexample} + The argument \meta{colname} won't appear as cell contents. It is an error if the the cells in \meta{colname} don't yield unique column names. + \end{pgfplotskey} + + \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). +\begin{codeexample}[] +\pgfplotstabletranspose[input colnames to=Input]\table{pgfplotstable.example3.dat} +\pgfplotstabletypeset[string type]\table +\end{codeexample} + Set \meta{name} to the empty string to disable this column. +\begin{codeexample}[] +\pgfplotstabletranspose[input colnames to=]\table{pgfplotstable.example3.dat} +\pgfplotstabletypeset[string type]\table +\end{codeexample} + \end{pgfplotskey} + + \begin{pgfplotskey}{table/columns=\marg{list} (initially empty)} + Inside of |\pgfplotstabletranspose|, this key handles which input columns shall be considered for the transposition. + + 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}. +\begin{codeexample}[] +\pgfplotstabletranspose[columns={a,b}]\table{pgfplotstable.example3.dat} +\pgfplotstabletypeset[string type]\table +\end{codeexample} + + Here is the only difference between |\pgfplotstabletranspose| and |\pgfplotstabletranspose*|: the version without `|*|' \emph{resets} the |columns| key before it starts whereas the version with `|*|' simply uses the actual content of |columns|. + \end{pgfplotskey} +\end{commandlist} + +\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}. +\begin{codeexample}[] +\foreach \x in {1,2,...,4} {Iterating \x. }% +\end{codeexample} + + A \PGFPlots\ related example could be +\begin{codeexample}[code only] +\foreach \i in {1,2,...,10} {\addplot table {datafile\i}; }% +\end{codeexample} +\end{command} + +\noindent The following loop commands come with \PGFPlots. They are similar to the powerful \Tikz\ |\foreach| loop command, which, however, is not always useful for table processing: the effect of its loop body end after each iteration. + +The following \PGFPlots\ looping macros are an alternative. + +\begin{command}{\pgfplotsforeachungrouped \meta{variable} |in| \meta{list} \marg{command}} + A specialised variant of |\foreach| which can do two things: it does not introduce extra groups while executing \meta{command} and it allows to invoke the math parser for (simple!) \meta{$x_0$}|,|\meta{$x_1$}|,...,|\meta{$x_n$} expressions. + +\begin{codeexample}[] +\def\allcollected{} +\pgfplotsforeachungrouped \x in {1,2,...,4} {Iterating \x. \edef\allcollected{\allcollected, \x}}% +All collected = \allcollected. +\end{codeexample} + + A more useful example might be to work with tables: + +\begin{codeexample}[code only] +\pgfplotsforeachungrouped \i in {1,2,...,10} {% + \pgfplotstablevertcat{\output}{datafile\i} % appends `datafile\i' -> `\output' +}% +% since it was ungrouped, \output is still defined (would not work +% with \foreach) +\end{codeexample} + + \paragraph{Remark: } The special syntax \meta{list}=\meta{$x_0$}|,|\meta{$x_1$}|,...,|\meta{$x_n$}, i.e.\ with two leading elements, followed by dots and a final element, invokes the math parser for the loop. Thus, it allows larger number ranges than any other syntax if |/pgf/fpu| is active. In all other cases, |\pgfplotsforeachungrouped| invokes |\foreach| and provides the results without \TeX\ groups. + +\end{command} + +\begin{command}{\pgfplotsinvokeforeach\marg{list} \marg{command}} + A variant of |\pgfplotsforeachungrouped| (and such also of |\foreach|) which replaces any occurence of |#1| inside of \meta{command} once for every element in \meta{list}. Thus, it actually assumes that \marg{command} is like a |\newcommand| body. + + In other words, \marg{command} is invoked for every element of \marg{list}. The actual element of \marg{list} is available as |#1|. + + As |\pgfplotsforeachungrouped|, this command does \emph{not} introduce extra scopes (i.e.\ it is ungrouped as well). + + The difference to |\foreach \x in |\meta{list}\marg{command} is subtle: the |\x| would \emph{not} be expanded wheres |#1| is. +\begin{codeexample}[] +\pgfkeys{ + otherstyle a/.code={[a]}, + otherstyle b/.code={[b]}, + otherstyle c/.code={[c]}, + otherstyle d/.code={[d]}} +\pgfplotsinvokeforeach{a,b,c,d} + {\pgfkeys{key #1/.style={otherstyle #1}}} +Invoke them: \pgfkeys{key a} \pgfkeys{key b} \pgfkeys{key c} \pgfkeys{key d} +\end{codeexample} +The counter example would use a macro (here |\x|) as loop argument: +\begin{codeexample}[] +\pgfkeys{ + otherstyle a/.code={[a]}, + otherstyle b/.code={[b]}, + otherstyle c/.code={[c]}, + otherstyle d/.code={[d]}} +\pgfplotsforeachungrouped \x in {a,b,c,d} + {\pgfkeys{key \x/.style={otherstyle \x}}} +Invoke them: \pgfkeys{key a} \pgfkeys{key b} \pgfkeys{key c} \pgfkeys{key d} +\end{codeexample} + + \paragraph{Restrictions:} you can't nest this command yet (since it does not introduce protection by scopes). +\end{command} \printindex \bibliographystyle{abbrv} %gerapali} %gerabbrv} %gerunsrt.bst} %gerabbrv}% gerplain} diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfshell_cos.sh b/Master/texmf-dist/doc/latex/pgfplots/pgfshell_cos.sh new file mode 100644 index 00000000000..69dfb98cfb0 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfshell_cos.sh @@ -0,0 +1 @@ +awk 'BEGIN{ pi=3.14159; N=10; for(i=0;i<=N;i++) print i,cos(i/N*pi);}' diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfshell_replot.sh b/Master/texmf-dist/doc/latex/pgfplots/pgfshell_replot.sh new file mode 100644 index 00000000000..43f9c74b10d --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfshell_replot.sh @@ -0,0 +1 @@ +cat pgfshell_cos.out diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/first3d.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/first3d.dat new file mode 100644 index 00000000000..3eb149fb39a --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/first3d.dat @@ -0,0 +1,19 @@ +0 0 0.8 +1 0 0.56 +2 0 0.5 +3 0 0.75 + +0 1 0.6 +1 1 0.3 +2 1 0.21 +3 1 0.3 + +0 2 0.68 +1 2 0.22 +2 2 0.25 +3 2 0.4 + +0 3 0.7 +1 3 0.5 +2 3 0.58 +3 3 0.9 diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/group-1.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/group-1.dat new file mode 100644 index 00000000000..9c4721977c1 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/group-1.dat @@ -0,0 +1,100 @@ + 0 0 + 0.101010101010101 0.003968337098046536 + 0.202020202020202 0.03879848139724037 + 0.303030303030303 0.07449681366571764 + 0.404040404040404 0.03062920324654983 + 0.5050505050505051 0.01274238518397149 + 0.6060606060606061 0.2249561797283897 + 0.7070707070707071 0.4999479827498307 + 0.8080808080808081 0.3981193574950731 + 0.9090909090909091 0.04027172337377245 + 1.01010101010101 0.1936933789812283 + 1.111111111111111 1.004297738910544 + 1.212121212121212 1.394932756973723 + 1.313131313131313 0.6658916995769133 + 1.414141414141414 1.603273008937967e-05 + 1.515151515151515 0.8992176669853079 + 1.616161616161616 2.486287413463038 + 1.717171717171717 2.385626888700214 + 1.818181818181818 0.6129492994007223 + 1.919191919191919 0.1885706238206871 + 2.02020202020202 2.510765515340476 + 2.121212121212121 4.499459697752282 + 2.222222222222222 2.997127051553131 + 2.323232323232323 0.2564675518688727 + 2.424242424242424 1.128754863930759 + 2.525252525252525 5.201522697121352 + 2.626262626262626 6.5398258996952 + 2.727272727272727 2.851902884472503 + 2.828282828282828 0.0002565216248327663 + 2.929292929292929 3.384809928188597 + 3.03030303030303 8.751916992779028 + 3.131313131313131 7.910955632915607 + 3.232323232323232 1.914281347858205 + 3.333333333333333 0.5827936373472342 + 3.434343434343434 7.288588222730711 + 3.535353535353535 12.49809835020434 + 3.636363636363636 7.988767667214107 + 3.737373737373737 0.6469864674324911 + 3.838383838383838 2.862664569705941 + 3.939393939393939 12.69242258873778 + 4.040404040404041 15.45826825380854 + 4.141414141414141 6.529005928469218 + 4.242424242424242 0.001298623373325026 + 4.343434343434343 7.493997184177516 + 4.444444444444445 18.84985620023903 + 4.545454545454545 16.62351426982987 + 4.646464646464646 3.908496570941216 + 4.747474747474747 1.210793135870907 + 4.848484848484849 14.59137448749025 + 4.94949494949495 24.49509441584871 + 5.05050505050505 15.3397495600035 + 5.151515151515151 1.197834293993105 + 5.252525252525253 5.422508419649889 + 5.353535353535354 23.50300336750087 + 5.454545454545454 28.13470646164054 + 5.555555555555555 11.66429730543301 + 5.656565656565657 0.004104214377206993 + 5.757575757575758 13.26010977185174 + 5.858585858585858 32.79392402811185 + 5.959595959595959 28.49610044960613 + 6.060606060606061 6.569712537567954 + 6.161616161616162 2.088293714396938 + 6.262626262626262 24.45198029548618 + 6.363636363636363 40.48929368541874 + 6.464646464646465 25.0167045899648 + 6.565656565656566 1.895367598559552 + 6.666666666666667 8.835604467381064 + 6.767676767676767 37.6590232455743 + 6.868686868686869 44.55324510452694 + 6.96969696969697 18.22496944963562 + 7.070707070707071 0.01001981363363793 + 7.171717171717171 20.71655274408158 + 7.272727272727272 50.59758797814782 + 7.373737373737374 43.50128113988929 + 7.474747474747475 9.872295948273999 + 7.575757575757575 3.231361198143108 + 7.676767676767676 36.9031639133886 + 7.777777777777778 60.47915735717622 + 7.878787878787879 36.98619168221489 + 7.979797979797979 2.726295179067634 + 8.080808080808081 13.12949999662517 + 8.181818181818182 55.18598991843011 + 8.282828282828282 64.69764837122634 + 8.383838383838384 26.17831427141698 + 8.484848484848484 0.02077647477786736 + 8.585858585858587 29.89680230611936 + 8.686868686868687 72.27396258780425 + 8.787878787878787 61.61139553525694 + 8.888888888888889 13.79086540037578 + 8.98989898989899 4.6564009604268 + 9.09090909090909 51.97758237687653 + 9.191919191919192 84.46276216028679 + 9.292929292929292 51.21470039350742 + 9.393939393939394 3.677679524057532 + 9.494949494949495 18.33196860253283 + 9.595959595959595 76.1091578096789 + 9.696969696969697 88.55134175370434 + 9.797979797979798 35.49172666505309 + 9.8989898989899 0.03848964729204756 + 10 40.83440224611729 diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/pgfplots_scatterdata4.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/pgfplots_scatterdata4.dat new file mode 100644 index 00000000000..6cc9d870fe1 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/pgfplots_scatterdata4.dat @@ -0,0 +1,144 @@ +l_0 l_1 l_2 +1 6 -1 +-1 -1 -1 +0 -1 -1 +-1 0 -1 +-1 -1 0 +1 -1 -1 +0 0 -1 +0 -1 0 +1 -1 6 +-1 1 -1 +-1 0 0 +0 7 -1 +-1 -1 1 +2 -1 -1 +1 0 -1 +1 -1 0 +0 1 -1 +0 -1 1 +0 -1 7 +-1 2 -1 +-1 1 0 +-1 8 -1 +-1 0 1 +-1 -1 2 +3 -1 -1 +2 0 -1 +2 -1 0 +1 1 -1 +1 -1 1 +0 2 -1 +8 0 -1 +0 -1 2 +-1 3 -1 +7 1 -1 +-1 2 0 +-1 1 1 +7 -1 1 +-1 0 2 +6 2 -1 +-1 -1 3 +4 -1 -1 +6 -1 2 +3 0 -1 +3 -1 0 +5 3 -1 +2 1 -1 +2 -1 1 +5 -1 3 +1 2 -1 +4 4 -1 +1 -1 2 +0 3 -1 +4 -1 4 +3 5 -1 +0 -1 3 +-1 4 -1 +-1 3 0 +-1 2 1 +-1 1 2 +3 -1 5 +-1 0 3 +-1 -1 4 +2 6 -1 +5 -1 -1 +4 0 -1 +4 -1 0 +3 1 -1 +3 -1 1 +2 -1 6 +2 2 -1 +1 7 -1 +2 -1 2 +1 3 -1 +1 -1 3 +1 -1 7 +0 4 -1 +0 8 -1 +0 -1 4 +-1 5 -1 +-1 4 0 +-1 3 1 +-1 2 2 +-1 1 3 +-1 0 4 +-1 -1 5 +6 -1 -1 +5 0 -1 +5 -1 0 +4 1 -1 +4 -1 1 +3 2 -1 +3 -1 2 +2 3 -1 +8 1 -1 +2 -1 3 +1 4 -1 +7 2 -1 +6 3 -1 +1 -1 4 +0 5 -1 +5 4 -1 +0 -1 5 +-1 6 -1 +-1 4 1 +4 5 -1 +-1 3 2 +-1 2 3 +-1 1 4 +-1 -1 6 +7 -1 -1 +3 6 -1 +6 0 -1 +6 -1 0 +5 1 -1 +5 -1 1 +4 2 -1 +4 -1 2 +2 7 -1 +3 3 -1 +3 -1 3 +2 4 -1 +1 8 -1 +2 -1 4 +1 5 -1 +1 -1 5 +0 6 -1 +0 -1 6 +-1 7 -1 +-1 -1 7 +8 -1 -1 +7 0 -1 +7 -1 0 +6 1 -1 +6 -1 1 +5 2 -1 +5 -1 2 +4 3 -1 +4 -1 3 +3 4 -1 +3 -1 4 +2 5 -1 +2 -1 5 +# vi: tabstop=20 nowrap nostartofline diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/pgfplotsexample4.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/pgfplotsexample4.dat new file mode 100644 index 00000000000..ff4c54c5eb6 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/pgfplotsexample4.dat @@ -0,0 +1,1123 @@ +x_0 x_1 f(x) +0 0 0 +0 0.03125 0 +0 0.0625 0 +0 0.09375 0 +0 0.125 0 +0 0.15625 0 +0 0.1875 0 +0 0.21875 0 +0 0.25 0 +0 0.28125 0 +0 0.3125 0 +0 0.34375 0 +0 0.375 0 +0 0.40625 0 +0 0.4375 0 +0 0.46875 0 +0 0.5 0 +0 0.53125 0 +0 0.5625 0 +0 0.59375 0 +0 0.625 0 +0 0.65625 0 +0 0.6875 0 +0 0.71875 0 +0 0.75 0 +0 0.78125 0 +0 0.8125 0 +0 0.84375 0 +0 0.875 0 +0 0.90625 0 +0 0.9375 0 +0 0.96875 0 +0 1 0 + +0.03125 0 0 +0.03125 0.03125 -4.5776367e-05 +0.03125 0.0625 -6.1035156e-05 +0.03125 0.09375 -7.6293945e-05 +0.03125 0.125 -6.1035156e-05 +0.03125 0.15625 -7.6293945e-05 +0.03125 0.1875 -6.1035156e-05 +0.03125 0.21875 -4.5776367e-05 +0.03125 0.25 0 +0.03125 0.28125 -1.5258789e-05 +0.03125 0.3125 0 +0.03125 0.34375 1.5258789e-05 +0.03125 0.375 6.1035156e-05 +0.03125 0.40625 7.6293945e-05 +0.03125 0.4375 0.00012207031 +0.03125 0.46875 0.00016784668 +0.03125 0.5 0.00024414062 +0.03125 0.53125 0.00022888184 +0.03125 0.5625 0.00024414062 +0.03125 0.59375 0.00025939941 +0.03125 0.625 0.00030517578 +0.03125 0.65625 0.00032043457 +0.03125 0.6875 0.00036621094 +0.03125 0.71875 0.0004119873 +0.03125 0.75 0.00048828125 +0.03125 0.78125 0.00050354004 +0.03125 0.8125 0.00054931641 +0.03125 0.84375 0.00059509277 +0.03125 0.875 0.00067138672 +0.03125 0.90625 0.00071716309 +0.03125 0.9375 0.00079345703 +0.03125 0.96875 0.00086975098 +0.03125 1 0.0009765625 + +0.0625 0 0 +0.0625 0.03125 -6.1035156e-05 +0.0625 0.0625 -6.1035156e-05 +0.0625 0.09375 -6.1035156e-05 +0.0625 0.125 0 +0.0625 0.15625 0 +0.0625 0.1875 6.1035156e-05 +0.0625 0.21875 0.00012207031 +0.0625 0.25 0.00024414062 +0.0625 0.28125 0.00024414062 +0.0625 0.3125 0.00030517578 +0.0625 0.34375 0.00036621094 +0.0625 0.375 0.00048828125 +0.0625 0.40625 0.00054931641 +0.0625 0.4375 0.00067138672 +0.0625 0.46875 0.00079345703 +0.0625 0.5 0.0009765625 +0.0625 0.53125 0.0010375977 +0.0625 0.5625 0.001159668 +0.0625 0.59375 0.0012817383 +0.0625 0.625 0.0014648438 +0.0625 0.65625 0.0015869141 +0.0625 0.6875 0.0017700195 +0.0625 0.71875 0.001953125 +0.0625 0.75 0.0021972656 +0.0625 0.78125 0.0023193359 +0.0625 0.8125 0.0025024414 +0.0625 0.84375 0.0026855469 +0.0625 0.875 0.0029296875 +0.0625 0.90625 0.003112793 +0.0625 0.9375 0.0033569336 +0.0625 0.96875 0.0036010742 +0.0625 1 0.00390625 + +0.09375 0 0 +0.09375 0.03125 -7.6293945e-05 +0.09375 0.0625 -6.1035156e-05 +0.09375 0.09375 -4.5776367e-05 +0.09375 0.125 6.1035156e-05 +0.09375 0.15625 7.6293945e-05 +0.09375 0.1875 0.00018310547 +0.09375 0.21875 0.00028991699 +0.09375 0.25 0.00048828125 +0.09375 0.28125 0.0005645752 +0.09375 0.3125 0.00073242188 +0.09375 0.34375 0.00090026855 +0.09375 0.375 0.001159668 +0.09375 0.40625 0.0013275146 +0.09375 0.4375 0.0015869141 +0.09375 0.46875 0.0018463135 +0.09375 0.5 0.0021972656 +0.09375 0.53125 0.0023956299 +0.09375 0.5625 0.0026855469 +0.09375 0.59375 0.0029754639 +0.09375 0.625 0.0033569336 +0.09375 0.65625 0.0036468506 +0.09375 0.6875 0.0040283203 +0.09375 0.71875 0.00440979 +0.09375 0.75 0.0048828125 +0.09375 0.78125 0.0052337646 +0.09375 0.8125 0.0056762695 +0.09375 0.84375 0.0061187744 +0.09375 0.875 0.006652832 +0.09375 0.90625 0.0070953369 +0.09375 0.9375 0.0076293945 +0.09375 0.96875 0.0081634521 +0.09375 1 0.0087890625 + +0.125 0 0 +0.125 0.03125 -6.1035156e-05 +0.125 0.0625 0 +0.125 0.09375 6.1035156e-05 +0.125 0.125 0.00024414062 +0.125 0.15625 0.00030517578 +0.125 0.1875 0.00048828125 +0.125 0.21875 0.00067138672 +0.125 0.25 0.0009765625 +0.125 0.28125 0.001159668 +0.125 0.3125 0.0014648438 +0.125 0.34375 0.0017700195 +0.125 0.375 0.0021972656 +0.125 0.40625 0.0025024414 +0.125 0.4375 0.0029296875 +0.125 0.46875 0.0033569336 +0.125 0.5 0.00390625 +0.125 0.53125 0.0043334961 +0.125 0.5625 0.0048828125 +0.125 0.59375 0.0054321289 +0.125 0.625 0.0061035156 +0.125 0.65625 0.006652832 +0.125 0.6875 0.0073242188 +0.125 0.71875 0.0079956055 +0.125 0.75 0.0087890625 +0.125 0.78125 0.0094604492 +0.125 0.8125 0.010253906 +0.125 0.84375 0.011047363 +0.125 0.875 0.011962891 +0.125 0.90625 0.012756348 +0.125 0.9375 0.013671875 +0.125 0.96875 0.014587402 +0.125 1 0.015625 + +0.15625 0 0 +0.15625 0.03125 -7.6293945e-05 +0.15625 0.0625 0 +0.15625 0.09375 7.6293945e-05 +0.15625 0.125 0.00030517578 +0.15625 0.15625 0.00044250488 +0.15625 0.1875 0.00073242188 +0.15625 0.21875 0.0010223389 +0.15625 0.25 0.0014648438 +0.15625 0.28125 0.0017852783 +0.15625 0.3125 0.0022583008 +0.15625 0.34375 0.0027313232 +0.15625 0.375 0.0033569336 +0.15625 0.40625 0.0038909912 +0.15625 0.4375 0.0045776367 +0.15625 0.46875 0.0052642822 +0.15625 0.5 0.0061035156 +0.15625 0.53125 0.0067901611 +0.15625 0.5625 0.0076293945 +0.15625 0.59375 0.0084686279 +0.15625 0.625 0.0094604492 +0.15625 0.65625 0.010360718 +0.15625 0.6875 0.011413574 +0.15625 0.71875 0.012466431 +0.15625 0.75 0.013671875 +0.15625 0.78125 0.014755249 +0.15625 0.8125 0.015991211 +0.15625 0.84375 0.017227173 +0.15625 0.875 0.018615723 +0.15625 0.90625 0.01991272 +0.15625 0.9375 0.021362305 +0.15625 0.96875 0.02281189 +0.15625 1 0.024414062 + +0.1875 0 0 +0.1875 0.03125 -6.1035156e-05 +0.1875 0.0625 6.1035156e-05 +0.1875 0.09375 0.00018310547 +0.1875 0.125 0.00048828125 +0.1875 0.15625 0.00073242188 +0.1875 0.1875 0.001159668 +0.1875 0.21875 0.0015869141 +0.1875 0.25 0.0021972656 +0.1875 0.28125 0.0026855469 +0.1875 0.3125 0.0033569336 +0.1875 0.34375 0.0040283203 +0.1875 0.375 0.0048828125 +0.1875 0.40625 0.0056762695 +0.1875 0.4375 0.006652832 +0.1875 0.46875 0.0076293945 +0.1875 0.5 0.0087890625 +0.1875 0.53125 0.0098266602 +0.1875 0.5625 0.011047363 +0.1875 0.59375 0.012268066 +0.1875 0.625 0.013671875 +0.1875 0.65625 0.015014648 +0.1875 0.6875 0.016540527 +0.1875 0.71875 0.018066406 +0.1875 0.75 0.019775391 +0.1875 0.78125 0.021362305 +0.1875 0.8125 0.023132324 +0.1875 0.84375 0.024902344 +0.1875 0.875 0.026855469 +0.1875 0.90625 0.028747559 +0.1875 0.9375 0.030822754 +0.1875 0.96875 0.032897949 +0.1875 1 0.03515625 + +0.21875 0 0 +0.21875 0.03125 -4.5776367e-05 +0.21875 0.0625 0.00012207031 +0.21875 0.09375 0.00028991699 +0.21875 0.125 0.00067138672 +0.21875 0.15625 0.0010223389 +0.21875 0.1875 0.0015869141 +0.21875 0.21875 0.0021514893 +0.21875 0.25 0.0029296875 +0.21875 0.28125 0.0036468506 +0.21875 0.3125 0.0045776367 +0.21875 0.34375 0.0055084229 +0.21875 0.375 0.006652832 +0.21875 0.40625 0.0077667236 +0.21875 0.4375 0.0090942383 +0.21875 0.46875 0.010421753 +0.21875 0.5 0.011962891 +0.21875 0.53125 0.013412476 +0.21875 0.5625 0.015075684 +0.21875 0.59375 0.016738892 +0.21875 0.625 0.018615723 +0.21875 0.65625 0.020462036 +0.21875 0.6875 0.022521973 +0.21875 0.71875 0.024581909 +0.21875 0.75 0.026855469 +0.21875 0.78125 0.029067993 +0.21875 0.8125 0.031494141 +0.21875 0.84375 0.033920288 +0.21875 0.875 0.036560059 +0.21875 0.90625 0.039169312 +0.21875 0.9375 0.041992188 +0.21875 0.96875 0.044815063 +0.21875 1 0.047851562 + +0.25 0 0 +0.25 0.03125 0 +0.25 0.0625 0.00024414062 +0.25 0.09375 0.00048828125 +0.25 0.125 0.0009765625 +0.25 0.15625 0.0014648438 +0.25 0.1875 0.0021972656 +0.25 0.21875 0.0029296875 +0.25 0.25 0.00390625 +0.25 0.28125 0.0048828125 +0.25 0.3125 0.0061035156 +0.25 0.34375 0.0073242188 +0.25 0.375 0.0087890625 +0.25 0.40625 0.010253906 +0.25 0.4375 0.011962891 +0.25 0.46875 0.013671875 +0.25 0.5 0.015625 +0.25 0.53125 0.017578125 +0.25 0.5625 0.019775391 +0.25 0.59375 0.021972656 +0.25 0.625 0.024414062 +0.25 0.65625 0.026855469 +0.25 0.6875 0.029541016 +0.25 0.71875 0.032226562 +0.25 0.75 0.03515625 +0.25 0.78125 0.038085938 +0.25 0.8125 0.041259766 +0.25 0.84375 0.044433594 +0.25 0.875 0.047851562 +0.25 0.90625 0.051269531 +0.25 0.9375 0.054931641 +0.25 0.96875 0.05859375 +0.25 1 0.0625 + +0.28125 0 0 +0.28125 0.03125 -1.5258789e-05 +0.28125 0.0625 0.00024414062 +0.28125 0.09375 0.0005645752 +0.28125 0.125 0.001159668 +0.28125 0.15625 0.0017852783 +0.28125 0.1875 0.0026855469 +0.28125 0.21875 0.0036468506 +0.28125 0.25 0.0048828125 +0.28125 0.28125 0.0061187744 +0.28125 0.3125 0.0076293945 +0.28125 0.34375 0.0092010498 +0.28125 0.375 0.011047363 +0.28125 0.40625 0.012924194 +0.28125 0.4375 0.015075684 +0.28125 0.46875 0.017288208 +0.28125 0.5 0.019775391 +0.28125 0.53125 0.022232056 +0.28125 0.5625 0.024963379 +0.28125 0.59375 0.027755737 +0.28125 0.625 0.030822754 +0.28125 0.65625 0.033920288 +0.28125 0.6875 0.03729248 +0.28125 0.71875 0.040725708 +0.28125 0.75 0.044433594 +0.28125 0.78125 0.048141479 +0.28125 0.8125 0.052124023 +0.28125 0.84375 0.056167603 +0.28125 0.875 0.06048584 +0.28125 0.90625 0.064834595 +0.28125 0.9375 0.069458008 +0.28125 0.96875 0.074142456 +0.28125 1 0.079101562 + +0.3125 0 0 +0.3125 0.03125 0 +0.3125 0.0625 0.00030517578 +0.3125 0.09375 0.00073242188 +0.3125 0.125 0.0014648438 +0.3125 0.15625 0.0022583008 +0.3125 0.1875 0.0033569336 +0.3125 0.21875 0.0045776367 +0.3125 0.25 0.0061035156 +0.3125 0.28125 0.0076293945 +0.3125 0.3125 0.0094604492 +0.3125 0.34375 0.011413574 +0.3125 0.375 0.013671875 +0.3125 0.40625 0.015991211 +0.3125 0.4375 0.018615723 +0.3125 0.46875 0.021362305 +0.3125 0.5 0.024414062 +0.3125 0.53125 0.02746582 +0.3125 0.5625 0.030822754 +0.3125 0.59375 0.034301758 +0.3125 0.625 0.038085938 +0.3125 0.65625 0.041931152 +0.3125 0.6875 0.046081543 +0.3125 0.71875 0.050354004 +0.3125 0.75 0.054931641 +0.3125 0.78125 0.059509277 +0.3125 0.8125 0.06439209 +0.3125 0.84375 0.069396973 +0.3125 0.875 0.074707031 +0.3125 0.90625 0.080078125 +0.3125 0.9375 0.085754395 +0.3125 0.96875 0.091552734 +0.3125 1 0.09765625 + +0.34375 0 0 +0.34375 0.03125 1.5258789e-05 +0.34375 0.0625 0.00036621094 +0.34375 0.09375 0.00090026855 +0.34375 0.125 0.0017700195 +0.34375 0.15625 0.0027313232 +0.34375 0.1875 0.0040283203 +0.34375 0.21875 0.0055084229 +0.34375 0.25 0.0073242188 +0.34375 0.28125 0.0092010498 +0.34375 0.3125 0.011413574 +0.34375 0.34375 0.013809204 +0.34375 0.375 0.016540527 +0.34375 0.40625 0.019363403 +0.34375 0.4375 0.022521973 +0.34375 0.46875 0.025863647 +0.34375 0.5 0.029541016 +0.34375 0.53125 0.033248901 +0.34375 0.5625 0.03729248 +0.34375 0.59375 0.041519165 +0.34375 0.625 0.046081543 +0.34375 0.65625 0.050735474 +0.34375 0.6875 0.055725098 +0.34375 0.71875 0.060897827 +0.34375 0.75 0.06640625 +0.34375 0.78125 0.071975708 +0.34375 0.8125 0.077880859 +0.34375 0.84375 0.083969116 +0.34375 0.875 0.090393066 +0.34375 0.90625 0.096908569 +0.34375 0.9375 0.10375977 +0.34375 0.96875 0.11079407 +0.34375 1 0.11816406 + +0.375 0 0 +0.375 0.03125 6.1035156e-05 +0.375 0.0625 0.00048828125 +0.375 0.09375 0.001159668 +0.375 0.125 0.0021972656 +0.375 0.15625 0.0033569336 +0.375 0.1875 0.0048828125 +0.375 0.21875 0.006652832 +0.375 0.25 0.0087890625 +0.375 0.28125 0.011047363 +0.375 0.3125 0.013671875 +0.375 0.34375 0.016540527 +0.375 0.375 0.019775391 +0.375 0.40625 0.023132324 +0.375 0.4375 0.026855469 +0.375 0.46875 0.030822754 +0.375 0.5 0.03515625 +0.375 0.53125 0.039611816 +0.375 0.5625 0.044433594 +0.375 0.59375 0.049499512 +0.375 0.625 0.054931641 +0.375 0.65625 0.06048584 +0.375 0.6875 0.06640625 +0.375 0.71875 0.072570801 +0.375 0.75 0.079101562 +0.375 0.78125 0.085754395 +0.375 0.8125 0.092773438 +0.375 0.84375 0.10003662 +0.375 0.875 0.10766602 +0.375 0.90625 0.11541748 +0.375 0.9375 0.12353516 +0.375 0.96875 0.13189697 +0.375 1 0.140625 + +0.40625 0 0 +0.40625 0.03125 7.6293945e-05 +0.40625 0.0625 0.00054931641 +0.40625 0.09375 0.0013275146 +0.40625 0.125 0.0025024414 +0.40625 0.15625 0.0038909912 +0.40625 0.1875 0.0056762695 +0.40625 0.21875 0.0077667236 +0.40625 0.25 0.010253906 +0.40625 0.28125 0.012924194 +0.40625 0.3125 0.015991211 +0.40625 0.34375 0.019363403 +0.40625 0.375 0.023132324 +0.40625 0.40625 0.027114868 +0.40625 0.4375 0.031494141 +0.40625 0.46875 0.036178589 +0.40625 0.5 0.041259766 +0.40625 0.53125 0.04649353 +0.40625 0.5625 0.052124023 +0.40625 0.59375 0.058059692 +0.40625 0.625 0.06439209 +0.40625 0.65625 0.07093811 +0.40625 0.6875 0.077880859 +0.40625 0.71875 0.085128784 +0.40625 0.75 0.092773438 +0.40625 0.78125 0.1006012 +0.40625 0.8125 0.10882568 +0.40625 0.84375 0.11735535 +0.40625 0.875 0.12628174 +0.40625 0.90625 0.13542175 +0.40625 0.9375 0.1449585 +0.40625 0.96875 0.15480042 +0.40625 1 0.16503906 + +0.4375 0 0 +0.4375 0.03125 0.00012207031 +0.4375 0.0625 0.00067138672 +0.4375 0.09375 0.0015869141 +0.4375 0.125 0.0029296875 +0.4375 0.15625 0.0045776367 +0.4375 0.1875 0.006652832 +0.4375 0.21875 0.0090942383 +0.4375 0.25 0.011962891 +0.4375 0.28125 0.015075684 +0.4375 0.3125 0.018615723 +0.4375 0.34375 0.022521973 +0.4375 0.375 0.026855469 +0.4375 0.40625 0.031494141 +0.4375 0.4375 0.036560059 +0.4375 0.46875 0.041992188 +0.4375 0.5 0.047851562 +0.4375 0.53125 0.053955078 +0.4375 0.5625 0.06048584 +0.4375 0.59375 0.067382812 +0.4375 0.625 0.074707031 +0.4375 0.65625 0.082336426 +0.4375 0.6875 0.090393066 +0.4375 0.71875 0.098815918 +0.4375 0.75 0.10766602 +0.4375 0.78125 0.11676025 +0.4375 0.8125 0.12628174 +0.4375 0.84375 0.13616943 +0.4375 0.875 0.14648438 +0.4375 0.90625 0.15710449 +0.4375 0.9375 0.16815186 +0.4375 0.96875 0.17956543 +0.4375 1 0.19140625 + +0.46875 0 0 +0.46875 0.03125 0.00016784668 +0.46875 0.0625 0.00079345703 +0.46875 0.09375 0.0018463135 +0.46875 0.125 0.0033569336 +0.46875 0.15625 0.0052642822 +0.46875 0.1875 0.0076293945 +0.46875 0.21875 0.010421753 +0.46875 0.25 0.013671875 +0.46875 0.28125 0.017288208 +0.46875 0.3125 0.021362305 +0.46875 0.34375 0.025863647 +0.46875 0.375 0.030822754 +0.46875 0.40625 0.036178589 +0.46875 0.4375 0.041992188 +0.46875 0.46875 0.048233032 +0.46875 0.5 0.054931641 +0.46875 0.53125 0.061965942 +0.46875 0.5625 0.069458008 +0.46875 0.59375 0.077377319 +0.46875 0.625 0.085754395 +0.46875 0.65625 0.094528198 +0.46875 0.6875 0.10375977 +0.46875 0.71875 0.11341858 +0.46875 0.75 0.12353516 +0.46875 0.78125 0.13401794 +0.46875 0.8125 0.1449585 +0.46875 0.84375 0.15632629 +0.46875 0.875 0.16815186 +0.46875 0.90625 0.18037415 +0.46875 0.9375 0.1930542 +0.46875 0.96875 0.2061615 +0.46875 1 0.21972656 + +0.5 0 0 +0.5 0.03125 0.00024414062 +0.5 0.0625 0.0009765625 +0.5 0.09375 0.0021972656 +0.5 0.125 0.00390625 +0.5 0.15625 0.0061035156 +0.5 0.1875 0.0087890625 +0.5 0.21875 0.011962891 +0.5 0.25 0.015625 +0.5 0.28125 0.019775391 +0.5 0.3125 0.024414062 +0.5 0.34375 0.029541016 +0.5 0.375 0.03515625 +0.5 0.40625 0.041259766 +0.5 0.4375 0.047851562 +0.5 0.46875 0.054931641 +0.5 0.5 0.0625 +0.5 0.53125 0.070556641 +0.5 0.5625 0.079101562 +0.5 0.59375 0.088134766 +0.5 0.625 0.09765625 +0.5 0.65625 0.10766602 +0.5 0.6875 0.11816406 +0.5 0.71875 0.12915039 +0.5 0.75 0.140625 +0.5 0.78125 0.15258789 +0.5 0.8125 0.16503906 +0.5 0.84375 0.17797852 +0.5 0.875 0.19140625 +0.5 0.90625 0.20532227 +0.5 0.9375 0.21972656 +0.5 0.96875 0.23461914 +0.5 1 0.25 + +0.53125 0 0 +0.53125 0.03125 0.00022888184 +0.53125 0.0625 0.0010375977 +0.53125 0.09375 0.0023956299 +0.53125 0.125 0.0043334961 +0.53125 0.15625 0.0067901611 +0.53125 0.1875 0.0098266602 +0.53125 0.21875 0.013412476 +0.53125 0.25 0.017578125 +0.53125 0.28125 0.022232056 +0.53125 0.3125 0.02746582 +0.53125 0.34375 0.033248901 +0.53125 0.375 0.039611816 +0.53125 0.40625 0.04649353 +0.53125 0.4375 0.053955078 +0.53125 0.46875 0.061965942 +0.53125 0.5 0.070556641 +0.53125 0.53125 0.079605103 +0.53125 0.5625 0.089233398 +0.53125 0.59375 0.099411011 +0.53125 0.625 0.11016846 +0.53125 0.65625 0.1214447 +0.53125 0.6875 0.13330078 +0.53125 0.71875 0.14570618 +0.53125 0.75 0.15869141 +0.53125 0.78125 0.17216492 +0.53125 0.8125 0.18621826 +0.53125 0.84375 0.20082092 +0.53125 0.875 0.21600342 +0.53125 0.90625 0.23170471 +0.53125 0.9375 0.24798584 +0.53125 0.96875 0.26481628 +0.53125 1 0.28222656 + +0.5625 0 0 +0.5625 0.03125 0.00024414062 +0.5625 0.0625 0.001159668 +0.5625 0.09375 0.0026855469 +0.5625 0.125 0.0048828125 +0.5625 0.15625 0.0076293945 +0.5625 0.1875 0.011047363 +0.5625 0.21875 0.015075684 +0.5625 0.25 0.019775391 +0.5625 0.28125 0.024963379 +0.5625 0.3125 0.030822754 +0.5625 0.34375 0.03729248 +0.5625 0.375 0.044433594 +0.5625 0.40625 0.052124023 +0.5625 0.4375 0.06048584 +0.5625 0.46875 0.069458008 +0.5625 0.5 0.079101562 +0.5625 0.53125 0.089233398 +0.5625 0.5625 0.10003662 +0.5625 0.59375 0.1114502 +0.5625 0.625 0.12353516 +0.5625 0.65625 0.13616943 +0.5625 0.6875 0.1494751 +0.5625 0.71875 0.16339111 +0.5625 0.75 0.17797852 +0.5625 0.78125 0.1930542 +0.5625 0.8125 0.20880127 +0.5625 0.84375 0.22515869 +0.5625 0.875 0.2421875 +0.5625 0.90625 0.25976562 +0.5625 0.9375 0.27801514 +0.5625 0.96875 0.296875 +0.5625 1 0.31640625 + +0.59375 0 0 +0.59375 0.03125 0.00025939941 +0.59375 0.0625 0.0012817383 +0.59375 0.09375 0.0029754639 +0.59375 0.125 0.0054321289 +0.59375 0.15625 0.0084686279 +0.59375 0.1875 0.012268066 +0.59375 0.21875 0.016738892 +0.59375 0.25 0.021972656 +0.59375 0.28125 0.027755737 +0.59375 0.3125 0.034301758 +0.59375 0.34375 0.041519165 +0.59375 0.375 0.049499512 +0.59375 0.40625 0.058059692 +0.59375 0.4375 0.067382812 +0.59375 0.46875 0.077377319 +0.59375 0.5 0.088134766 +0.59375 0.53125 0.099411011 +0.59375 0.5625 0.1114502 +0.59375 0.59375 0.12416077 +0.59375 0.625 0.13763428 +0.59375 0.65625 0.15168762 +0.59375 0.6875 0.16650391 +0.59375 0.71875 0.18199158 +0.59375 0.75 0.19824219 +0.59375 0.78125 0.21504211 +0.59375 0.8125 0.23260498 +0.59375 0.84375 0.25083923 +0.59375 0.875 0.26983643 +0.59375 0.90625 0.28941345 +0.59375 0.9375 0.30975342 +0.59375 0.96875 0.33076477 +0.59375 1 0.35253906 + +0.625 0 0 +0.625 0.03125 0.00030517578 +0.625 0.0625 0.0014648438 +0.625 0.09375 0.0033569336 +0.625 0.125 0.0061035156 +0.625 0.15625 0.0094604492 +0.625 0.1875 0.013671875 +0.625 0.21875 0.018615723 +0.625 0.25 0.024414062 +0.625 0.28125 0.030822754 +0.625 0.3125 0.038085938 +0.625 0.34375 0.046081543 +0.625 0.375 0.054931641 +0.625 0.40625 0.06439209 +0.625 0.4375 0.074707031 +0.625 0.46875 0.085754395 +0.625 0.5 0.09765625 +0.625 0.53125 0.11016846 +0.625 0.5625 0.12353516 +0.625 0.59375 0.13763428 +0.625 0.625 0.15258789 +0.625 0.65625 0.16815186 +0.625 0.6875 0.18457031 +0.625 0.71875 0.20172119 +0.625 0.75 0.21972656 +0.625 0.78125 0.23834229 +0.625 0.8125 0.2578125 +0.625 0.84375 0.27801514 +0.625 0.875 0.29907227 +0.625 0.90625 0.32073975 +0.625 0.9375 0.34326172 +0.625 0.96875 0.36651611 +0.625 1 0.390625 + +0.65625 0 0 +0.65625 0.03125 0.00032043457 +0.65625 0.0625 0.0015869141 +0.65625 0.09375 0.0036468506 +0.65625 0.125 0.006652832 +0.65625 0.15625 0.010360718 +0.65625 0.1875 0.015014648 +0.65625 0.21875 0.020462036 +0.65625 0.25 0.026855469 +0.65625 0.28125 0.033920288 +0.65625 0.3125 0.041931152 +0.65625 0.34375 0.050735474 +0.65625 0.375 0.06048584 +0.65625 0.40625 0.07093811 +0.65625 0.4375 0.082336426 +0.65625 0.46875 0.094528198 +0.65625 0.5 0.10766602 +0.65625 0.53125 0.1214447 +0.65625 0.5625 0.13616943 +0.65625 0.59375 0.15168762 +0.65625 0.625 0.16815186 +0.65625 0.65625 0.18531799 +0.65625 0.6875 0.20343018 +0.65625 0.71875 0.22233582 +0.65625 0.75 0.2421875 +0.65625 0.78125 0.26271057 +0.65625 0.8125 0.28417969 +0.65625 0.84375 0.30644226 +0.65625 0.875 0.32965088 +0.65625 0.90625 0.3535614 +0.65625 0.9375 0.37841797 +0.65625 0.96875 0.40406799 +0.65625 1 0.43066406 + +0.6875 0 0 +0.6875 0.03125 0.00036621094 +0.6875 0.0625 0.0017700195 +0.6875 0.09375 0.0040283203 +0.6875 0.125 0.0073242188 +0.6875 0.15625 0.011413574 +0.6875 0.1875 0.016540527 +0.6875 0.21875 0.022521973 +0.6875 0.25 0.029541016 +0.6875 0.28125 0.03729248 +0.6875 0.3125 0.046081543 +0.6875 0.34375 0.055725098 +0.6875 0.375 0.06640625 +0.6875 0.40625 0.077880859 +0.6875 0.4375 0.090393066 +0.6875 0.46875 0.10375977 +0.6875 0.5 0.11816406 +0.6875 0.53125 0.13330078 +0.6875 0.5625 0.1494751 +0.6875 0.59375 0.16650391 +0.6875 0.625 0.18457031 +0.6875 0.65625 0.20343018 +0.6875 0.6875 0.22332764 +0.6875 0.71875 0.24407959 +0.6875 0.75 0.26586914 +0.6875 0.78125 0.28839111 +0.6875 0.8125 0.31195068 +0.6875 0.84375 0.33636475 +0.6875 0.875 0.36181641 +0.6875 0.90625 0.38806152 +0.6875 0.9375 0.41534424 +0.6875 0.96875 0.44348145 +0.6875 1 0.47265625 + +0.71875 0 0 +0.71875 0.03125 0.0004119873 +0.71875 0.0625 0.001953125 +0.71875 0.09375 0.00440979 +0.71875 0.125 0.0079956055 +0.71875 0.15625 0.012466431 +0.71875 0.1875 0.018066406 +0.71875 0.21875 0.024581909 +0.71875 0.25 0.032226562 +0.71875 0.28125 0.040725708 +0.71875 0.3125 0.050354004 +0.71875 0.34375 0.060897827 +0.71875 0.375 0.072570801 +0.71875 0.40625 0.085128784 +0.71875 0.4375 0.098815918 +0.71875 0.46875 0.11341858 +0.71875 0.5 0.12915039 +0.71875 0.53125 0.14570618 +0.71875 0.5625 0.16339111 +0.71875 0.59375 0.18199158 +0.71875 0.625 0.20172119 +0.71875 0.65625 0.22233582 +0.71875 0.6875 0.24407959 +0.71875 0.71875 0.26673889 +0.71875 0.75 0.29052734 +0.71875 0.78125 0.31517029 +0.71875 0.8125 0.34094238 +0.71875 0.84375 0.36763 +0.71875 0.875 0.39544678 +0.71875 0.90625 0.42414856 +0.71875 0.9375 0.45397949 +0.71875 0.96875 0.48472595 +0.71875 1 0.51660156 + +0.75 0 0 +0.75 0.03125 0.00048828125 +0.75 0.0625 0.0021972656 +0.75 0.09375 0.0048828125 +0.75 0.125 0.0087890625 +0.75 0.15625 0.013671875 +0.75 0.1875 0.019775391 +0.75 0.21875 0.026855469 +0.75 0.25 0.03515625 +0.75 0.28125 0.044433594 +0.75 0.3125 0.054931641 +0.75 0.34375 0.06640625 +0.75 0.375 0.079101562 +0.75 0.40625 0.092773438 +0.75 0.4375 0.10766602 +0.75 0.46875 0.12353516 +0.75 0.5 0.140625 +0.75 0.53125 0.15869141 +0.75 0.5625 0.17797852 +0.75 0.59375 0.19824219 +0.75 0.625 0.21972656 +0.75 0.65625 0.2421875 +0.75 0.6875 0.26586914 +0.75 0.71875 0.29052734 +0.75 0.75 0.31640625 +0.75 0.78125 0.34326172 +0.75 0.8125 0.37133789 +0.75 0.84375 0.40039062 +0.75 0.875 0.43066406 +0.75 0.90625 0.46191406 +0.75 0.9375 0.49438477 +0.75 0.96875 0.52783203 +0.75 1 0.5625 + +0.78125 0 0 +0.78125 0.03125 0.00050354004 +0.78125 0.0625 0.0023193359 +0.78125 0.09375 0.0052337646 +0.78125 0.125 0.0094604492 +0.78125 0.15625 0.014755249 +0.78125 0.1875 0.021362305 +0.78125 0.21875 0.029067993 +0.78125 0.25 0.038085938 +0.78125 0.28125 0.048141479 +0.78125 0.3125 0.059509277 +0.78125 0.34375 0.071975708 +0.78125 0.375 0.085754395 +0.78125 0.40625 0.1006012 +0.78125 0.4375 0.11676025 +0.78125 0.46875 0.13401794 +0.78125 0.5 0.15258789 +0.78125 0.53125 0.17216492 +0.78125 0.5625 0.1930542 +0.78125 0.59375 0.21504211 +0.78125 0.625 0.23834229 +0.78125 0.65625 0.26271057 +0.78125 0.6875 0.28839111 +0.78125 0.71875 0.31517029 +0.78125 0.75 0.34326172 +0.78125 0.78125 0.37239075 +0.78125 0.8125 0.40283203 +0.78125 0.84375 0.43437195 +0.78125 0.875 0.46722412 +0.78125 0.90625 0.50114441 +0.78125 0.9375 0.53637695 +0.78125 0.96875 0.57270813 +0.78125 1 0.61035156 + +0.8125 0 0 +0.8125 0.03125 0.00054931641 +0.8125 0.0625 0.0025024414 +0.8125 0.09375 0.0056762695 +0.8125 0.125 0.010253906 +0.8125 0.15625 0.015991211 +0.8125 0.1875 0.023132324 +0.8125 0.21875 0.031494141 +0.8125 0.25 0.041259766 +0.8125 0.28125 0.052124023 +0.8125 0.3125 0.06439209 +0.8125 0.34375 0.077880859 +0.8125 0.375 0.092773438 +0.8125 0.40625 0.10882568 +0.8125 0.4375 0.12628174 +0.8125 0.46875 0.1449585 +0.8125 0.5 0.16503906 +0.8125 0.53125 0.18621826 +0.8125 0.5625 0.20880127 +0.8125 0.59375 0.23260498 +0.8125 0.625 0.2578125 +0.8125 0.65625 0.28417969 +0.8125 0.6875 0.31195068 +0.8125 0.71875 0.34094238 +0.8125 0.75 0.37133789 +0.8125 0.78125 0.40283203 +0.8125 0.8125 0.43572998 +0.8125 0.84375 0.46984863 +0.8125 0.875 0.50537109 +0.8125 0.90625 0.54205322 +0.8125 0.9375 0.58013916 +0.8125 0.96875 0.6194458 +0.8125 1 0.66015625 + +0.84375 0 0 +0.84375 0.03125 0.00059509277 +0.84375 0.0625 0.0026855469 +0.84375 0.09375 0.0061187744 +0.84375 0.125 0.011047363 +0.84375 0.15625 0.017227173 +0.84375 0.1875 0.024902344 +0.84375 0.21875 0.033920288 +0.84375 0.25 0.044433594 +0.84375 0.28125 0.056167603 +0.84375 0.3125 0.069396973 +0.84375 0.34375 0.083969116 +0.84375 0.375 0.10003662 +0.84375 0.40625 0.11735535 +0.84375 0.4375 0.13616943 +0.84375 0.46875 0.15632629 +0.84375 0.5 0.17797852 +0.84375 0.53125 0.20082092 +0.84375 0.5625 0.22515869 +0.84375 0.59375 0.25083923 +0.84375 0.625 0.27801514 +0.84375 0.65625 0.30644226 +0.84375 0.6875 0.33636475 +0.84375 0.71875 0.36763 +0.84375 0.75 0.40039062 +0.84375 0.78125 0.43437195 +0.84375 0.8125 0.46984863 +0.84375 0.84375 0.50666809 +0.84375 0.875 0.54498291 +0.84375 0.90625 0.58454895 +0.84375 0.9375 0.62561035 +0.84375 0.96875 0.66801453 +0.84375 1 0.71191406 + +0.875 0 0 +0.875 0.03125 0.00067138672 +0.875 0.0625 0.0029296875 +0.875 0.09375 0.006652832 +0.875 0.125 0.011962891 +0.875 0.15625 0.018615723 +0.875 0.1875 0.026855469 +0.875 0.21875 0.036560059 +0.875 0.25 0.047851562 +0.875 0.28125 0.06048584 +0.875 0.3125 0.074707031 +0.875 0.34375 0.090393066 +0.875 0.375 0.10766602 +0.875 0.40625 0.12628174 +0.875 0.4375 0.14648438 +0.875 0.46875 0.16815186 +0.875 0.5 0.19140625 +0.875 0.53125 0.21600342 +0.875 0.5625 0.2421875 +0.875 0.59375 0.26983643 +0.875 0.625 0.29907227 +0.875 0.65625 0.32965088 +0.875 0.6875 0.36181641 +0.875 0.71875 0.39544678 +0.875 0.75 0.43066406 +0.875 0.78125 0.46722412 +0.875 0.8125 0.50537109 +0.875 0.84375 0.54498291 +0.875 0.875 0.58618164 +0.875 0.90625 0.62872314 +0.875 0.9375 0.67285156 +0.875 0.96875 0.71844482 +0.875 1 0.765625 + +0.90625 0 0 +0.90625 0.03125 0.00071716309 +0.90625 0.0625 0.003112793 +0.90625 0.09375 0.0070953369 +0.90625 0.125 0.012756348 +0.90625 0.15625 0.01991272 +0.90625 0.1875 0.028747559 +0.90625 0.21875 0.039169312 +0.90625 0.25 0.051269531 +0.90625 0.28125 0.064834595 +0.90625 0.3125 0.080078125 +0.90625 0.34375 0.096908569 +0.90625 0.375 0.11541748 +0.90625 0.40625 0.13542175 +0.90625 0.4375 0.15710449 +0.90625 0.46875 0.18037415 +0.90625 0.5 0.20532227 +0.90625 0.53125 0.23170471 +0.90625 0.5625 0.25976562 +0.90625 0.59375 0.28941345 +0.90625 0.625 0.32073975 +0.90625 0.65625 0.3535614 +0.90625 0.6875 0.38806152 +0.90625 0.71875 0.42414856 +0.90625 0.75 0.46191406 +0.90625 0.78125 0.50114441 +0.90625 0.8125 0.54205322 +0.90625 0.84375 0.58454895 +0.90625 0.875 0.62872314 +0.90625 0.90625 0.6743927 +0.90625 0.9375 0.72174072 +0.90625 0.96875 0.77067566 +0.90625 1 0.82128906 + +0.9375 0 0 +0.9375 0.03125 0.00079345703 +0.9375 0.0625 0.0033569336 +0.9375 0.09375 0.0076293945 +0.9375 0.125 0.013671875 +0.9375 0.15625 0.021362305 +0.9375 0.1875 0.030822754 +0.9375 0.21875 0.041992188 +0.9375 0.25 0.054931641 +0.9375 0.28125 0.069458008 +0.9375 0.3125 0.085754395 +0.9375 0.34375 0.10375977 +0.9375 0.375 0.12353516 +0.9375 0.40625 0.1449585 +0.9375 0.4375 0.16815186 +0.9375 0.46875 0.1930542 +0.9375 0.5 0.21972656 +0.9375 0.53125 0.24798584 +0.9375 0.5625 0.27801514 +0.9375 0.59375 0.30975342 +0.9375 0.625 0.34326172 +0.9375 0.65625 0.37841797 +0.9375 0.6875 0.41534424 +0.9375 0.71875 0.45397949 +0.9375 0.75 0.49438477 +0.9375 0.78125 0.53637695 +0.9375 0.8125 0.58013916 +0.9375 0.84375 0.62561035 +0.9375 0.875 0.67285156 +0.9375 0.90625 0.72174072 +0.9375 0.9375 0.7723999 +0.9375 0.96875 0.82476807 +0.9375 1 0.87890625 + +0.96875 0 0 +0.96875 0.03125 0.00086975098 +0.96875 0.0625 0.0036010742 +0.96875 0.09375 0.0081634521 +0.96875 0.125 0.014587402 +0.96875 0.15625 0.02281189 +0.96875 0.1875 0.032897949 +0.96875 0.21875 0.044815063 +0.96875 0.25 0.05859375 +0.96875 0.28125 0.074142456 +0.96875 0.3125 0.091552734 +0.96875 0.34375 0.11079407 +0.96875 0.375 0.13189697 +0.96875 0.40625 0.15480042 +0.96875 0.4375 0.17956543 +0.96875 0.46875 0.2061615 +0.96875 0.5 0.23461914 +0.96875 0.53125 0.26481628 +0.96875 0.5625 0.296875 +0.96875 0.59375 0.33076477 +0.96875 0.625 0.36651611 +0.96875 0.65625 0.40406799 +0.96875 0.6875 0.44348145 +0.96875 0.71875 0.48472595 +0.96875 0.75 0.52783203 +0.96875 0.78125 0.57270813 +0.96875 0.8125 0.6194458 +0.96875 0.84375 0.66801453 +0.96875 0.875 0.71844482 +0.96875 0.90625 0.77067566 +0.96875 0.9375 0.82476807 +0.96875 0.96875 0.88069153 +0.96875 1 0.93847656 + +1 0 0 +1 0.03125 0.0009765625 +1 0.0625 0.00390625 +1 0.09375 0.0087890625 +1 0.125 0.015625 +1 0.15625 0.024414062 +1 0.1875 0.03515625 +1 0.21875 0.047851562 +1 0.25 0.0625 +1 0.28125 0.079101562 +1 0.3125 0.09765625 +1 0.34375 0.11816406 +1 0.375 0.140625 +1 0.40625 0.16503906 +1 0.4375 0.19140625 +1 0.46875 0.21972656 +1 0.5 0.25 +1 0.53125 0.28222656 +1 0.5625 0.31640625 +1 0.59375 0.35253906 +1 0.625 0.390625 +1 0.65625 0.43066406 +1 0.6875 0.47265625 +1 0.71875 0.51660156 +1 0.75 0.5625 +1 0.78125 0.61035156 +1 0.8125 0.66015625 +1 0.84375 0.71191406 +1 0.875 0.765625 +1 0.90625 0.82128906 +1 0.9375 0.87890625 +1 0.96875 0.93847656 +1 1 1 + diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/pgfplotsexample4_grid.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/pgfplotsexample4_grid.dat new file mode 100644 index 00000000000..1bcdfac1d9b --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/pgfplotsexample4_grid.dat @@ -0,0 +1,291 @@ +x_0 x_1 f(x) +0 0 0 +0 0.03125 0 +0 0.0625 0 +0 0.09375 0 +0 0.125 0 +0 0.15625 0 +0 0.1875 0 +0 0.21875 0 +0 0.25 0 +0 0.28125 0 +0 0.3125 0 +0 0.34375 0 +0 0.375 0 +0 0.40625 0 +0 0.4375 0 +0 0.46875 0 +0 0.5 0 +0 0.53125 0 +0 0.5625 0 +0 0.59375 0 +0 0.625 0 +0 0.65625 0 +0 0.6875 0 +0 0.71875 0 +0 0.75 0 +0 0.78125 0 +0 0.8125 0 +0 0.84375 0 +0 0.875 0 +0 0.90625 0 +0 0.9375 0 +0 0.96875 0 +0 1 0 + +0.03125 0 0 +0.03125 0.5 0.00024414062 +0.03125 1 0.0009765625 + +0.0625 0 0 +0.0625 0.25 0.00024414062 +0.0625 0.5 0.0009765625 +0.0625 0.75 0.0021972656 +0.0625 1 0.00390625 + +0.09375 0 0 +0.09375 0.5 0.0021972656 +0.09375 1 0.0087890625 + +0.125 0 0 +0.125 0.125 0.00024414062 +0.125 0.25 0.0009765625 +0.125 0.375 0.0021972656 +0.125 0.5 0.00390625 +0.125 0.625 0.0061035156 +0.125 0.75 0.0087890625 +0.125 0.875 0.011962891 +0.125 1 0.015625 + +0.15625 0 0 +0.15625 0.5 0.0061035156 +0.15625 1 0.024414062 + +0.1875 0 0 +0.1875 0.25 0.0021972656 +0.1875 0.5 0.0087890625 +0.1875 0.75 0.019775391 +0.1875 1 0.03515625 + +0.21875 0 0 +0.21875 0.5 0.011962891 +0.21875 1 0.047851562 + +0.25 0 0 +0.25 0.0625 0.00024414062 +0.25 0.125 0.0009765625 +0.25 0.1875 0.0021972656 +0.25 0.25 0.00390625 +0.25 0.3125 0.0061035156 +0.25 0.375 0.0087890625 +0.25 0.4375 0.011962891 +0.25 0.5 0.015625 +0.25 0.5625 0.019775391 +0.25 0.625 0.024414062 +0.25 0.6875 0.029541016 +0.25 0.75 0.03515625 +0.25 0.8125 0.041259766 +0.25 0.875 0.047851562 +0.25 0.9375 0.054931641 +0.25 1 0.0625 + +0.28125 0 0 +0.28125 0.5 0.019775391 +0.28125 1 0.079101562 + +0.3125 0 0 +0.3125 0.25 0.0061035156 +0.3125 0.5 0.024414062 +0.3125 0.75 0.054931641 +0.3125 1 0.09765625 + +0.34375 0 0 +0.34375 0.5 0.029541016 +0.34375 1 0.11816406 + +0.375 0 0 +0.375 0.125 0.0021972656 +0.375 0.25 0.0087890625 +0.375 0.375 0.019775391 +0.375 0.5 0.03515625 +0.375 0.625 0.054931641 +0.375 0.75 0.079101562 +0.375 0.875 0.10766602 +0.375 1 0.140625 + +0.40625 0 0 +0.40625 0.5 0.041259766 +0.40625 1 0.16503906 + +0.4375 0 0 +0.4375 0.25 0.011962891 +0.4375 0.5 0.047851562 +0.4375 0.75 0.10766602 +0.4375 1 0.19140625 + +0.46875 0 0 +0.46875 0.5 0.054931641 +0.46875 1 0.21972656 + +0.5 0 0 +0.5 0.03125 0.00024414062 +0.5 0.0625 0.0009765625 +0.5 0.09375 0.0021972656 +0.5 0.125 0.00390625 +0.5 0.15625 0.0061035156 +0.5 0.1875 0.0087890625 +0.5 0.21875 0.011962891 +0.5 0.25 0.015625 +0.5 0.28125 0.019775391 +0.5 0.3125 0.024414062 +0.5 0.34375 0.029541016 +0.5 0.375 0.03515625 +0.5 0.40625 0.041259766 +0.5 0.4375 0.047851562 +0.5 0.46875 0.054931641 +0.5 0.5 0.0625 +0.5 0.53125 0.070556641 +0.5 0.5625 0.079101562 +0.5 0.59375 0.088134766 +0.5 0.625 0.09765625 +0.5 0.65625 0.10766602 +0.5 0.6875 0.11816406 +0.5 0.71875 0.12915039 +0.5 0.75 0.140625 +0.5 0.78125 0.15258789 +0.5 0.8125 0.16503906 +0.5 0.84375 0.17797852 +0.5 0.875 0.19140625 +0.5 0.90625 0.20532227 +0.5 0.9375 0.21972656 +0.5 0.96875 0.23461914 +0.5 1 0.25 + +0.53125 0 0 +0.53125 0.5 0.070556641 +0.53125 1 0.28222656 + +0.5625 0 0 +0.5625 0.25 0.019775391 +0.5625 0.5 0.079101562 +0.5625 0.75 0.17797852 +0.5625 1 0.31640625 + +0.59375 0 0 +0.59375 0.5 0.088134766 +0.59375 1 0.35253906 + +0.625 0 0 +0.625 0.125 0.0061035156 +0.625 0.25 0.024414062 +0.625 0.375 0.054931641 +0.625 0.5 0.09765625 +0.625 0.625 0.15258789 +0.625 0.75 0.21972656 +0.625 0.875 0.29907227 +0.625 1 0.390625 + +0.65625 0 0 +0.65625 0.5 0.10766602 +0.65625 1 0.43066406 + +0.6875 0 0 +0.6875 0.25 0.029541016 +0.6875 0.5 0.11816406 +0.6875 0.75 0.26586914 +0.6875 1 0.47265625 + +0.71875 0 0 +0.71875 0.5 0.12915039 +0.71875 1 0.51660156 + +0.75 0 0 +0.75 0.0625 0.0021972656 +0.75 0.125 0.0087890625 +0.75 0.1875 0.019775391 +0.75 0.25 0.03515625 +0.75 0.3125 0.054931641 +0.75 0.375 0.079101562 +0.75 0.4375 0.10766602 +0.75 0.5 0.140625 +0.75 0.5625 0.17797852 +0.75 0.625 0.21972656 +0.75 0.6875 0.26586914 +0.75 0.75 0.31640625 +0.75 0.8125 0.37133789 +0.75 0.875 0.43066406 +0.75 0.9375 0.49438477 +0.75 1 0.5625 + +0.78125 0 0 +0.78125 0.5 0.15258789 +0.78125 1 0.61035156 + +0.8125 0 0 +0.8125 0.25 0.041259766 +0.8125 0.5 0.16503906 +0.8125 0.75 0.37133789 +0.8125 1 0.66015625 + +0.84375 0 0 +0.84375 0.5 0.17797852 +0.84375 1 0.71191406 + +0.875 0 0 +0.875 0.125 0.011962891 +0.875 0.25 0.047851562 +0.875 0.375 0.10766602 +0.875 0.5 0.19140625 +0.875 0.625 0.29907227 +0.875 0.75 0.43066406 +0.875 0.875 0.58618164 +0.875 1 0.765625 + +0.90625 0 0 +0.90625 0.5 0.20532227 +0.90625 1 0.82128906 + +0.9375 0 0 +0.9375 0.25 0.054931641 +0.9375 0.5 0.21972656 +0.9375 0.75 0.49438477 +0.9375 1 0.87890625 + +0.96875 0 0 +0.96875 0.5 0.23461914 +0.96875 1 0.93847656 + +1 0 0 +1 0.03125 0.0009765625 +1 0.0625 0.00390625 +1 0.09375 0.0087890625 +1 0.125 0.015625 +1 0.15625 0.024414062 +1 0.1875 0.03515625 +1 0.21875 0.047851562 +1 0.25 0.0625 +1 0.28125 0.079101562 +1 0.3125 0.09765625 +1 0.34375 0.11816406 +1 0.375 0.140625 +1 0.40625 0.16503906 +1 0.4375 0.19140625 +1 0.46875 0.21972656 +1 0.5 0.25 +1 0.53125 0.28222656 +1 0.5625 0.31640625 +1 0.59375 0.35253906 +1 0.625 0.390625 +1 0.65625 0.43066406 +1 0.6875 0.47265625 +1 0.71875 0.51660156 +1 0.75 0.5625 +1 0.78125 0.61035156 +1 0.8125 0.66015625 +1 0.84375 0.71191406 +1 0.875 0.765625 +1 0.90625 0.82128906 +1 0.9375 0.87890625 +1 0.96875 0.93847656 +1 1 1 + diff --git a/Master/texmf-dist/doc/latex/pgfplots/plotdata/scattercl.dat b/Master/texmf-dist/doc/latex/pgfplots/plotdata/scattercl.dat new file mode 100644 index 00000000000..359de7b0811 --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/plotdata/scattercl.dat @@ -0,0 +1,13 @@ +x y label +0.1 0.15 a +0.45 0.27 c +0.02 0.17 a +0.06 0.1 a +0.9 0.5 b +0.5 0.3 c +0.85 0.52 b +0.12 0.05 a +0.73 0.45 b +0.53 0.25 c +0.76 0.5 b +0.55 0.32 c diff --git a/Master/texmf-dist/doc/latex/pgfplots/texmf.cnf b/Master/texmf-dist/doc/latex/pgfplots/texmf.cnf new file mode 100644 index 00000000000..9a104eb686c --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/texmf.cnf @@ -0,0 +1,81 @@ +% Part 3: Array and other sizes for TeX (and Metafont and MetaPost). +% +% If you want to change some of these sizes only for a certain TeX +% variant, the usual dot notation works, e.g., +% main_memory.hugetex = 20000000 +% +% If a change here appears to be ignored, try redumping the format file +% with fmtutil-sys. + +% Memory. Must be less than 8,000,000 total. +% +% main_memory is relevant only to initex, extra_mem_* only to non-ini. +% Thus, have to redump the .fmt file after changing main_memory; to add +% to existing fmt files, increase extra_mem_*. (To get an idea of how +% much, try \tracingstats=2 in your TeX source file; +% web2c/tests/memtest.tex might also be interesting.) +% +% To increase space for boxes (as might be needed by, e.g., PiCTeX), +% increase extra_mem_bot. +% +% 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 +extra_mem_top = 10000000 % extra high memory for chars, tokens, etc. +extra_mem_bot = 10000000 % extra low memory for boxes, glue, breakpoints, etc. + +% Words of font info for TeX (total size of all TFM files, approximately). +% Must be >= 20000 and <= 4000000 (without tex.ch changes). +%font_mem_size = 1200000 + +% Total number of fonts. Must be >= 50 and <= 2000 (without tex.ch changes). +%font_max = 2000 + +% Extra space for the hash table of control sequences (which allows 10K +% names as distributed). +%hash_extra = 50000 + +% Max number of characters in all strings, including all error messages, +% help texts, font names, control sequences. These values apply to TeX and MP. +%pool_size = 1250000 +% Minimum pool space after TeX/MP's own strings; must be at least +% 25000 less than pool_size, but doesn't need to be nearly that large. +%string_vacancies = 90000 +% Maximum number of strings. +%max_strings = 100000 +% min pool space left after loading .fmt +%pool_free = 47500 + +% Buffer size. TeX uses the buffer to contain input lines, but macro +% expansion works by writing material into the buffer and reparsing the +% line. As a consequence, certain constructs require the buffer to be +% very large, even though most documents can be handled with a small value. +%buf_size = 200000 + +% Hyphenation trie. The maximum possible is 4194303 (ssup_trie_size in +% the sources), but we don't need that much. The value here suffices +% for all known free hyphenation patterns to be loaded simultaneously +% (as TeX Live does). +% +%trie_size = 400000 + +%hyph_size = 8191 % prime number of hyphenation exceptions, >610, <32767. + % http://primes.utm.edu/curios/page.php/8191.html +%nest_size = 500 % simultaneous semantic levels (e.g., groups) +%max_in_open = 15 % simultaneous input files and error insertions +%param_size = 10000 % simultaneous macro parameters +save_size = 150000 % for saving values outside current group +stack_size = 150000 % simultaneous input sources + + + + +% It's probably inadvisable to change these. At any rate, we must have: +% 45 < error_line < 255; +% 30 < half_error_line < error_line - 15; +% 60 <= max_print_line; +% These apply to Metafont and MetaPost as well. +error_line = 254 +half_error_line = 127 +max_print_line = 32000 diff --git a/Master/texmf-dist/doc/latex/pgfplots/todo.txt b/Master/texmf-dist/doc/latex/pgfplots/todo.txt index a38eda7be85..780eb01a8a0 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/todo.txt +++ b/Master/texmf-dist/doc/latex/pgfplots/todo.txt @@ -1,19 +1,702 @@ +todo legend: +'-' means: not yet processed, is still to do +'+' means: processed +'X' means: has been checked and deleted +'~' means: partially processed + ------------------------------------------------------------- Testing ------------------------------------------------------------- last test verifications: - pgf CVS pgf 2.00 -pgfplotstests 2009-02-16 2009-02-16 -manual 2009-02-16 2009-02-16 -example latex for 1.2 2009-02-16 -example context for 1.2 2009-02-16 -example plain tex for 1.2 2009-02-16 + pgf CVS pgf 2.00 pgf 2.00+compat=default +pgfplotstests 2009-12-30 2009-12-30 2009-12-30 +manual 2009-12-29 2009-12-30 +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 + +I NEED MORE TESTS! +The test suite needs to be developed! + ++ tests for scan line length stuff for all input methods ++ tests for the placement of tick scale labels ++ test whether title placement works as it ought to do in previous versions +- test 'colormap access=direct' ++ test all z buffer variants ++ test gnuplot and log sampling 3D +- test log sampling in 3D ++ verify mesh/ordering=colwise +- test of compat keys + -> can they be used as arguments for an axis? ++ test those tickpos num keys! especially in combination with axis line + variations. Also test ticklabel pos + +------------------------------------------------------------- +USER INTERFACE DECISIONS +------------------------------------------------------------- + +- the axis line combination styles can't be adjusted for 3D because they are + evaluated too early. + +------------------------------------------------------------- +MISC +------------------------------------------------------------- + ++ disable pgfplots CVS? + +- documentation todo: + + table + error bar expr + + document examples for 3d LINE plots. + + the 'tick label anchor' is something which I do not understand myselfes. + It was some ad-hoc fix for something, but for what!? + there is a fixme in the manual + + document the external lib -- it is now part of pgfplots! + also document the file href thing + + the '\x mode' key is hard to find. The same holds for 'log basis \x'. + + docs of clickable lib is not up to date (for log basis \x) + + document the trafo shift of scatter/@pre marker code. + + compat mode + -> perhaps in preliminary section. + + 'variable y' + - label placement methods: + + '[xyz]label shift', + + 'ticklabel cs', + + '[xyz]ticklabel cs', + + special anchors + + 'near ticklabel', + + 'near [xyz]ticklabel', + + special 'sloped' feature + + '/tikz/sloped' for labels, + + '/tikz/sloped like [xyz] axis' + + every 3d description + + every 3d view {<h>}{<v>}/.try + + the legend feature for mesh/surf plots: + 'every mesh legend' style and the default 'legend image code' + + document how to make line plots in 3d + - perhaps: display KNOWN key paths in key definitions in gray, not in red? + + check if area cycle list is documented + + nodes near coords + + the 'cube' mark and its parameters 'cube/size [xyz]' + + provide a TEXMF config file which sets appropriate limits! + + document the anchors which are only local to an axis! + - document how to fix problems with overlapping axis labels. + + add 3D scatter plot examples + + there are still several FIXMEs in the docs + + provide sample config file for miktex and document how to enable it + -> necessary if someone wants to use the external lib! + X document which is the default view of matlab or gnuplot! + + document the 'to listener' feature. + + \pgfplotsmathviewdepthxyz and \pgfplotsmathfloatviewdepthxyz + + document the trafo shift of scatter/@pre marker code. + + provide direct pdf link to pgfplotstable.pdf as in hyperref? + + check if area cycle list is documented + + nodes near coords + + the 'cube' mark and its parameters 'cube/size [xyz]' + + provide a TEXMF config file which sets appropriate limits! + + the 'surf' and 'mesh' plots belong to /pgfplots, not /tikz. + + it is not documented how to provide braces exactly in parametric plots + + the key prefix checker in docs is broken, see /pgfplots//tikz/sloped like x axis + + finish the auto-generation of hyperlinks: + + something like |\pgfplotsset{| doesn't work properly: + + the argument will become '' + + the UI introduces closed braces + + replace \declaretext and |...| things by appropriate macros. + + disable this expensive stuff during image externalization + + generate labels for command keys, commands and environments automatically + + check if it is possible to create links within codeexamples automatically or semiautomatically + + document the macros + + verify that the spacing is not affected by the new labels + - the cycle list args could be highlighted -- but leads to bug! + + document some important pgf macros somewhere: + \pgfmathparse, \pgfmathresult, \node, \matrix, \tikzset, \pgfeov, \pgfkeysvalueof, \pgfkeysgetvalue, + /tikz/xshift, /tikz/yshift + + it would be interesting to parse coordinates '(...)'. + + the \pgfplotsshortxystylekey things need to be adapted. + + optimize manual for display speed by reducing complicated 3D plots (interp shadings) + -> the old shader=interp values are still there, with comment signs! + Check them! + + document 'allow reversal of rel axis cs' + + document unbounded coords key + + document z buffer + + document 'plot box ratio={<x>}{<y>}{<z>}' (for 3D axes) + + document support for nonuniform colormap specs + + |log basis [xyz]| key + + scatter src vs point meta + + 3D + + view and its subkeys az and el + + color bars + + document that 'shader=interp' produces smaller pdfs, requires less time to + typeset in TeX and produces less time to display in acroread. + At least for large grids. + + \addplot now detects behavior options and style options automatically + + there are a lot of reference to behavior (or behaviour) options in the text + + document expression plotting in plot table + + meta expr (does that need another name!?) + + 'axis description cs' + + colormap access=map|direct key. + + document simplified format of colormaps + + changes in alignment + + end-of-scanline markers + + 'rel axis cs' + + API for \pgfplotspointouternormalvectorofaxis + + API for + + \pgfplotsqpointoutsideofaxis + + \pgfplotsqpointoutsideofaxisrel + X \pgfplotsqpointoutsideofaxistransformed + X \pgfplotspointoutsideofticklabelaxis + X API for \pgfplotspointticklabelcs + + API for \pgfplotsvalueoflargesttickdimen + + API for \pgfplotsticklabelaxisspec + + API for \pgfplotspointunit[xyz] + + API for \pgfplotsconvertunittocoordinate{[xyz]}{dimen} + X API for \pgfplotsqpointxyzabsolutesize + + API for \pgfplotsunit[xyz]length + + API for \pgfplotsunit[xyz]invlength + + API for \pgfplotspointaxisorigin + + API for \pgfplotspointdescriptionxy and the q variant + + API for \pgfplotspointaxisxy + + API for \pgfplotspointrelaxisxy + X API for surf shading library + -> document the problems with pdf2ps for surf shading! pdf2ps samples + that stuff manually instead of producing level3 postscript! + +- clickable lib: + I have the impression that acroread fires warnings only for the manual - not always when the clickable lib is used. Why!? + +------------------------------------------------------------- +PGF / TikZ Development: +------------------------------------------------------------- + - external lib: 'list and make' does not work together with \include (aux files!) or other file writing things -- at least not if one tries to do that in parallel. + + consider the "plot function" patch from Andy Schlaikjer + + it seems fadings don't work correctly with externalization!? + - include addition of Christophe Jorssen for MD5 checksums in external lib + + write new sub-package 'pgfmanual.sty' which contains a good user interface to the manual styles, environments and all that. + + external lib: catcode changes inside of pictures do not work properly. + - the fpu can't be used inside of paths. That should be fixed. + -> the problem is that paths may use \pgfmath... routines directly. + -> this should work! At least with the public math macros \pgfmathadd. + The \pgfmathadd@ might be implemented differently. + + 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 + feature. + - fix landscape bug (pdflscape) in external lib (PGF) + + the pgf math parser has wrong precedence for '-' prefix op: + exp(-x^2) is wrong. + - pack the default 'system call' for dvips etc into drivers! + - active '|' characters result in compilation bugs (\usepackage{program}) + - 'text height=1em' realisieren mit [node font units]1em + +- compatiblity code todo: + - the example for plot graphics (with view=0{90}) doesn't work. + -> that's the 'exp(0-x^2)' bug which is still in pgf 2.00! ------------------------------------------------------------- BUGS / FIXES ------------------------------------------------------------- ++ the tick pos stuff works (puh!) + However, there is an inconsistency with the axis lines stuff: + 'axis lines=left,tick pos=right' + will yield almost the same effect as 'axis lines=right'. However, the + 'axislinesnum' still assumes it is at the left. + Thus, there are potentially some inconsistencies... + -> BUT THAT'S LOW PRIORITY + ++ tick align=outside doesn't seem to affect the ticklabel cs although it + probably should (tests in pgfplotstest.axislines.tex). + -> check also display styles for labels! + +- manual: 'label style' and 'xticklabel style' are not auto-crossrefed + ++ extra ticks do not work with '3d box=complete' + +- the FPU has somewhere spaces; at least it treats them differently from \pgfmathparse. + +- I have seen that 'plot table' with very large files can produce pool size problems -- even if the coordinates are all filtered away. + In other words: the code can't simply read a file and throw its contents away. + The problem appears to be some math parsing using the table/x expr and friends. + 'pool size = names of control sequences and file name' + -> the math parser could be improved with \ifcsname + ++ I had just a problem with 'log basis y=2' : the x axis also used basis 2, but minor ticks basis 10. + It was the second plot; the first had also log basis x=2 + -> the problem is the 'log basis ticks' style which changes 'log number + format code' globally for the axis. + +- axis lines and 3D: some tick lines are not drawn, see manual examples + +- check for placement of tick scale label for compat=newest + -> 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: + the label placement style is incompatible. + - axis lines=center + reversed axes: the tick labels are placed somewhat + too near the axis... see the test in alignment subsection of testcases + -> perhaps the "normal vector" points into the wrong direction? + -> It is the tick@offset computed in the tick label placement + routines. I have implemented special handling for this case, but I + do not really understand the problem. + FIXME + - tickpos is wrong + +- 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. + +- one can't provide 'scale' as argument to a (3d) axis + + ++ axis line variations: they pose problems for + a) 3d axes + b) reversed axes. + + ++ The Adobe Reader crashes on p 68 of the manual (while Foxit shows and +prints without complaint). 27.11.2009 reported by J. Goebel + ++ check the old code with 'pgfplotsautoanchor' for tick labels. + 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. + ++ the pretty printer appends '{}' to known csnames. ++ the pretty printer appends ')' to |(| ++ the xref to |scatter src| is broken... why? + ++ \thisrow inside of column creation does not respect aliases +- \getthisrow still has to be fixed + ++ the \pgfplotsretval key is uses globally and locally. Fix that. + There is also \pgfplotslocretval which should be eliminated. + Better: use \pgfplotsretval for local ret vals and + \pgfplotsglobretval for global ones. Better still: avoid global return values if possible. + +- it may still happen that log-axes get only *one* tick label (in my case 10^{-0.2}). That should never happen. + The range is about ymin=4.7e-1, ymax=9.5e-1 + ++ 3D and special axis lines doesn't work at all. + ++ sanitize 'plot file' by appending '0' coordinates at the end of the current line + ++ the 'z buffer=auto' key in every mesh is stupid. What if I don't want it!? +- log samples in plot expression for 3D plots +- different log bases and gnuplot ++ 3D gnuplot: z buffer fails (see tests) + +- I tried placing a named coordinate inside one axis and using it in + another. It failed. + % CF: The axis is drawn inside of its own picture which will only be shifted if everything has been drawn. That will be the origin of this problem I guess + + Miraculously I can use the coordinate outside axis env. So I have + reached the following solution: + ++ allocate a \newread for input files to avoid compatibility problems with other packages. + +- the compatibility things should be enabled automatically for some parts: + - 3D + - color bars + - reversed axes + +- plot coordinates doesn't check too well if + 1. \addplot3 is used but only two coords are given + 2. \addplot is given but three coordinates are provided (also for plot expression) + ++ gnuplot: set terminal table seems to be deprecated. +- gnuplot and 3D + -> I need a shared interface to prepare the required keys for expression plotting ++ scatter/pre mark styles should OVERWRITE the current setting instead of append. Provide additional keys with suffix '*' which provide the "append" feature. + ++ if view leads to ||e_i| == 0, this results in an error somewhere (infty + occurs) + +X change UI of ticklabel cs: provide an option 'ticklabel cs:[<interpreter>]<coord>,<dist>' which specifies how to understand "<coord>". Choices: + - 'display' + - 'rel coord' + - 'abs coord' + is that really useful ? + ++ plot3 table: the scanline detection does not always work (seems to need an empty line as last line) + ++ the \pgfplotsdeclareborderanchorforticklabelaxis does not work if someone changes the shape! The shape changes occur AFTER my command. + -> solution idea: implement some sort of "unknown shape handler"! + ++ 3D: very long labels are not completely correct: they may run into the axis. + +- the compat things are not yet complete: I wanted to check when it is really necessary (for example if 'x dir' is used) + ++ the 'check tick show thing doesn't work for non-boxed axes! + ++ BUG IN \jobname with " --->> IS INVALID ++ there is 'samples y' and 'variable y' but 'y domain'! + ++ ich habe gerade das Problem, dass ich fuer einen Plot nur eine + y Achse moechte. Ich habe "axis y line=right" gesetzt. Nur sobald + ich "axis x line=none" einfuege, verschwinden die Tickmarken an + der y Achse... + +- the nodes near coords feature produces unexpected results when used together + with markers -> this is due to the default configuration of scatter plots. + + ++ provide a meaningful error message when mesh plots fail due to unbounded + coords - I don't want to waste time with checks. (could I optimize the + checks??) + ++ I have removed the 'surf' option from \addplot3 {...}; -> check it ! it + should be moved to some default style; maybe cycle list or so? + ++ the auto z buffer may lead to errors if cols and/or rows is empty. + ++ FPU and '<' operator didn't work!? + ++ the 'prepare@#1coord' doesn't check for unbounded coords. Besides, it appears + to be wrong - maybe I should rewrite it. + ++ one my recent changes leads to 'meta data 25.000' is unbounded for whatever + reasons. Furthermore, \addplot3 {x^2}; lead to a bunch or error messages. + ++ forget plot and legends do not work + +- check whether /pgfplots/ keys are processed properly in legends. This is + certainly not the case for the \label/\ref legend! + -> which ones are the problem? +- 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) + -> that's because the '\addplot' ybar can't distinguish between /tikz and + /pgfplots paths! + + To stay compatible, I need to make sure that \addplot[ybar] actually uses + \addplot[/tikz/ybar]. That's how it is documented. + ++ colorbar impl: + + determine correct height such that it has the same as its parent. + + determine all styles which need to be inherited. + + fix the style-restore routine! It eats too many '#' chars! + + ++ the 'plot table' detection of gnuplot files is buggy - it can fail for example + if there are 2 comment lines and 3 columns (with headers) + ++ the xtick=data feature doesn't check for double occurances. + ++ It appears the (new) placement of tick scale labels is wrong for 2d axes. + ++ the '[xyz]ticklabels' key does NOT work any longer! It fails if some of the + ticks fall outside of limits. + ++ the meta stuff is not sanitized: check for NaN or INF. + ++ z buffer=sort does not respect LOG axes properly! + ++ z buffer=auto should be added. + ++ table package and unbalanced columns appears to be buggy. + -> need use 'nan' + ++ I observed problems with the 'title' placement in 3D plots!? + +- axis equal for semilog plots is not correct (?) ++ something is wrong with the log basis stuff. Did I mess something up!? + + fix this! For reasons of compatibility, it might suffice to modify the + clickable lib since the display of the plots is correct (base 10). Any + internal UI special cases might still rely on base e (and it might be more + efficient to rescale just tick labels!) + - document that special handling to reduce confusion! + ++ context incompatibility: \definecolor is defined differently in context, leading to bugs (occurs for 'mapped color') + ++ + \pgfplotsset{every axis/.append style={font=\footnotesize}, + tick label style={/pgf/number format/1000 sep=}, + xticklabel={\pgfkeys{/pgf/fpu}% + \pgfmathparse{round(exp(\tick))}% + \pgfmathprintnumber{\pgfmathresult}}} + + to see the real tick numbers in a semilogxaxis, but when I use the former + fake plot as the first of my plots, it behaves as if I hadn't used these + options. When written in any other position it works as expected. + + More specifically, this only happens when using xtick=data. If the ticks are + specified as a list, the bug doesn't show up. + + ++ there is 'ticklabel dist' and 'label shift'. Use the same naming convention! + ++ 'shader=interp' still does not support 'ordering=colwise' + ++ 'view={0}{90}' does not set label styles correctly + +- backwards compatibility problem: + axis descriptions can't contain /pgfplots/ styles any longer! This is a key + path issue :-( + ++ the clickable lib output is shifted somehow (at least for log plots). It + appears it does not respect the new alignment stuff properly. + ++ the 3d labels still need a good initial style - and a user interface to set + it. + idea: 'every 3d axis' is a style which can set axis descriptions or tikz keys. + + all descriptions styles need to be set up before they are used. + + changes to these styles may only be done when the axis' dimension (d=2 or + d=3) is clear - and the associated initial styles are installed. Then, + modifications may be applied. + 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) + + plots R^2 -> R^3 (parametric) + -> may require 'u' and 'v' + - using other variable names (see 'set dummy') + + ydomain is not set + ++ the \x, \y, \z etc. macros in the table expression plotter should be + eliminated! They pose name conflicts. + ++ the '/tikz/variable' key can't be provided as argument to an axis (missing + family) + ++ the tick scale labels need to be placed with 'ticklabel cs'. That's difficult, + but necessary. + + 2D + needs to be improved! + + 3D + ++ the color bar is an "axis description" -- but it can't be placed like other + axis descriptions! + +- BACKWARDS COMPATIBILITY BREAKDOWNS: + 1. reversed axes with "manual hacks": + - the description cs won't be reversed for negative axes, + - the anchors won't be reversed for negative axes, + - the 'ticklabel pos' key is no longer reversed for reversed axes, + 2. Skewed axes + - the description cs won't be skewed for skewed axes (and it should not), + 3. the tick label positioning may not work as before. + - possible solution: write the required "activation" option into every code example! + +- the backwards-compatibility issue can be solved by + - a '/pgfplots/labels near ticks' style whichs sets [xy]label style + - a '/pgfplots/labels absolute' style for the "classical" default + - small text below (above?) every code example + "% preamble: \pgfplotsset{labels near ticks,width=7cm}" +- the "reversed axis" backwards compatibility problem could be solved by + a special mode which restores the old, deprecated handling of + - anchors, + - description cs, + - tick label positioning, + - ... + this could be checked easily: if x<0pt (or y<0pt), the backwards compatibility modes must + be enabled otherwise it is an error. +- Ideas: + restore ALL OLD features and provide them using a compatibility interface! + - The compatibiltiy interface operates using pgfkeys and simply exchanges + implementations with \let. + - I should derive conditions which require a choice between compatibility + mode and normal mode. + + UI: + compatibility/<feature name>=before 1.3|newest + compatibility=before 1.3|newest (a style which sets all) + + I suppose this affects + + \pgfplotspointdescriptionxy + + the "real" anchors + ++ I need a solution to rotate labels correctly and make alignment in a good way + -> probably the "sloped" method of pgf? + + ++ I fear the 'plot gnuplot[<opts>]' thing does not properly process <opts>. + ++ what happens if 'point meta [min,max]' is provided inside of \addplot? + ++ it appears the recent changes update the bounding box - disabling overlay for + tick labels + ++ the 'legend image code' is again buggy! Try ybar! This here is the reason: one + can't set draw/fill mode from within a scope! + \begin{tikzpicture} + \scope[fill=blue,draw=red] + \path (0,0) circle (10pt); + \endscope + \end{tikzpicture} + + ++ the 'x={(x1,x2)}' option(s) are buggy: the complete vector length needs to be + scaled by the datascaling routine, not the single components. + ++ ticklabel interval stuff doesn't work properly + ++ potential problem with stacked y bar and semilogyaxis, see bug report per Mail + ++ stacked plots do not sanitize the input arguments: it may happen that too few + (or too much) coordinates are given. + ++ Memory limitations in MikTeX: + see http://blog.antiblau.de/2009/04/21/speicherlimits-von-miktex-erhoehen/ + ++ shader=faceted must be provided after 'surf'. That's not what I wanted. + ideas to fix the problem: + 1. introduce a further 'mode' which enables drawing and/or + filling for meshmode. + So, 'mesh' would set fill to false and the fill color is irrelevant. + For 'surf', the state could depend on the current shader - either + only the fill color or both, fill and draw color will be used. + ++ BUG: empty axes and one of my newer changes (bblowerleft) conflicts. + +- BUG: in empty axes, 'xtick=\empty' is ignored. + +- finish impl of ticklabel pos. + I should use the same thing for tickpos as well. + And: the default arg processing which uses ticklabel pos = tickpos needs to be + fixed. + the 2D axes are wrong. + + +- The automatic tick labeling sometimes produces inconsistent or confusing + labels: + 1. engineering and fixed number style are mixed up. + 2. If range of an axis is so small that the labels differ only on the third + decimal, still only two decimals are used. + ++ axis y line=right, FAILS to produce correctly placed tick + labels -> only in manual!? + ++ ymin=0.9 is ok while ymin=.9 is not ok -- update number parser. + ++ legends are currently broken! + ++ the tick labels on axis boundaries are often missing. I suppose this is due to + rounding inaccuracies or '<' instead of '<='. check that! + ++ new alignment: origin anchors for unfinished axis is not updated. + +- 3D: axis equal implementation might not be correct (at least not for view + special cases) + +X perhaps the ASCIIHexEncode would be a useful addition for the pdftex driver of + surfshading as well...? + no, it isn't. pdf2ps still generates huge sampled postscript files. + +- 3D: + error bars and + stacked plots + need to be updated. + +- the \thisrow commands in the table package does not (always) respect aliases! + ++ check for the @non@legend@options - I suppose they are deprecated now and + waste computation time. + ++ the new key processing which skips every /tikz option in \addplot might not be + correct - there are several plot related exceptions like /tikz/id etc which + SHOULD be processed. Make sure I have all of them. + Besides: what happens if someone uses /tikz/draw explicitly? I am not sure if + that hurts... ++ the recent search path construction WILL also set tikz options during + \addplot. + There won't be any paths during \addplot - but I am not sure if there can be + any scoping problems related to the graphics state. + -> that stuff produces problems with /tikz/ybar vs. /pgfplots/ybar! + + + ++ the view argument should be similar to gnuplot /matlab. I fear I have + exchanged some of the directions. + In matlab, the argument is '{yaw}{pitch}' instead of '{pitch}{yaw}' + Furthermore, the rotation axes are different. view={0}{0} in matlab shows + the x axis horizontally and the z axis vertically - the view direction is + (0,1,0) -- for me, this would be (0,0,1). + ++ pdf2ps still fails for interp shader - it has a limitcheck exception. Perhaps + the number of bits is too large for ps? + -> a very small stupid test with 8 bits per coordinate and 8 bits per cdata + worked + +- interp shader is displayed transparently in evince + ++ clickable plot lib produces visual artefacts in acroread + -> the 'hidden' flag appears to be incompatible with figure environments!? + - fixed in recent hyperref drivers of pdftex; was actually a bug of hyperref + +- 3D: the use of \addplot3 and \addplot is not sanitized properly + Possibilities: + - used \addplot when \addplot3 should have been used + - used \addplot3 where \addplot should have been used. + What can happen here!? Shouldn't this work in every case? + + ++ the 'current axis' node is not defined until the first axis descriptions are + drawn. That should be fixed by defining the low-weight shape before processing + the stored path commands. + ++ The following fails: + \addplot+[ + black] plot coordinates { (0,0) (1,1) }; + +- The "xtick" value is not applied unless there is a coordinate in the x range: + -> that's the handling of empty figures... + + not working: + + \begin{axis}[xtick=0] + \end{axis} + + not working: + + \begin{axis}[xmin=-5,xmax=5,xtick=0] + \end{axis} + + not working: + + \begin{axis}[xmin=-5,xmax=5,xtick=0] + \addplot coordinates { (-10, 0) }; + \end{axis} + + + working: + + \begin{axis}[xmin=-5,xmax=5,xtick=0] + \addplot coordinates { (0, 0) }; + \end{axis} + +- think about basic level commands for the axis lines -- this should also allow + \pgfpathclose ! + + +- the arguments to plot file[#1] and plot table[#1] are not consistent with + rest. They need to be treated as behavior options (maybe in a different key + path). +- check behavior options provided to table[] and file[] and so - is that + correct? + + ++ the \ref command should be \protect'ed in LaTeX captions + ++ the ticklable dist feature NEEDS anchors. + + - the plot mark code invokes a lot of math parsing routines - which is a waste of time in my opinion. All expressions etc. have already been parsed. Potential for optimization! @@ -27,6 +710,13 @@ BUGS / FIXES - no, it works only partially: draw=none or fill=none works as expected. But 'blue' disables filling!? + - Possible fix: + Overwrite \filltrue \fillfalse, \drawtrue, \drawfalse: + they should set a further boolean '\drawbooleanhasbeenset' and + '\fillbooleanhasbeenset'. + -> Replace the \pgfusepathqfillstroke if and only if the respective + booleans have been set *explicitly*. If they are unchanged, fall back to + a "reasonable" default. + provide example for colormap changes - that should also verify the correctness @@ -38,32 +728,22 @@ BUGS / FIXES + improve docs for scatter plots: + 'only marks' is also a scatter plot! -- check behavior options provided to table[] and file[] and so - is that - correct? - + something with the table package appears to be buggy!? + the plot table[] search path is not good - it should include /pgfplots -- introduce backwards compatibility with old pgfmathfloat.code.tex file ++ introduce backwards compatibility with old pgfmathfloat.code.tex file [ not interesting for pgfplots 1.2, only for pgfplots 1.1 !] + there is a bug related with empty axes - I suppose in conjunction with the tickmin/max feature (it won't be reset properly) -- the arguments to plot file[#1] and plot table[#1] are not consistent with - rest. They need to be treated as behavior options (maybe in a different key - path). - -- there is a space too much in some behavior messages (occured in test +X there is a space too much in some behavior messages (occured in test processing) X introduce backwards compatibility with old pgfmathfloat.code.tex file -- the pgf math parser has wrong precedence for '-' prefix op: - exp(-x^2) is wrong. - - the auto-generated tick labels for non-unit-distance log axes could be better. + verify that the domain key always accepts the extended data range @@ -75,9 +755,6 @@ X introduce backwards compatibility with old pgfmathfloat.code.tex file + the stacked plots impl is not yet in logical coords - that means it won't work with non-standard unit vectors! -- fix version stuff in package header -- introduce CVS Header Variables in every sourcefile - + The floating point math routines should be put into a separate library. Provide compatibility support for that in pgfplots! @@ -156,12 +833,12 @@ X scaled ticks is not properly implemented for log axes - In 3D case axis [xyz] line != box, there is just ONE hyperplane. My implementation works only if either ALL are box or ALL are 'middle'. -- 3D case : which hyperplane gets tick LABELS? ++ 3D case : which hyperplane gets tick LABELS? The current implementation based on '[xzy]ticklabel pos' is not sufficient -- 3D case: something fails with disabledatascaling ++ 3D case: something fails with disabledatascaling -- 3D case : grid lines work correctly, but they are not satisfactory. ++ 3D case : grid lines work correctly, but they are not satisfactory. I'd like grid lines in the background only. - 3D case : tick/grid lines are on top of the axis lines. This leads to @@ -193,6 +870,35 @@ X scaled ticks is not properly implemented for log axes + the clickable library does *not* work inside of figure environments + -> yes. That's fixed; was a bug in hyperref. + - I could try to re-implement it without insdljs. + Ideas: + - the document catalog's names dictionary needs to '/JavaScript + [(<arbitrary script name>) <dictionary with JS>]' entry. + The <dictionary with JS> contains document level javascript. + - it is very simple to generate these entries for my case. + Unfortunately, this may be incompatible with 'insdljs' or other tools + which write DLJS. + - I am not sure why the floating figures of TeX produce an + incompatibility here. It appears the 'hidden' flag in the form fields + are the problem - if that is the case, I'd need to reimplement the + form annotations (which could be more difficult). + +- javascript stuff does not work if the complete figure is rotated (sidewaysfigure). + +- javascript: incompatiblity with external library: + 1. filenames: \jobname contains characters with incompatible catcodes and + that funny insdljs package tries to assemble macros with these + characters. + -> fixed; I simply use pgfplotsJS as temporary file name. + 2. the images as such have corrupted forms + -> Can be fixed if + \usepackage{eforms} + is used BEFORE loading pgf. The reason: \begin{Form} and the shipout-hackery + of the pgf externalization bite each other. + \begin{Form} must come before the shipout hackery of pgf. + 3. \includegraphics does not preserve PDF forms. + @@ -219,21 +925,6 @@ X error recovery: it is sometimes almost impossible to find errors in + bug in insdljs: workaround introduced. + bug in my code fixed -- javascript stuff does not work if the complete figure is rotated (sidewaysfigure). - -- javascript: incompatiblity with external library: - 1. filenames: \jobname contains characters with incompatible catcodes and - that funny insdljs package tries to assemble macros with these - characters. - -> fixed; I simply use pgfplotsJS as temporary file name. - 2. the images as such have corrupted forms - -> Can be fixed if - \usepackage{eforms} - is used BEFORE loading pgf. The reason: \begin{Form} and the shipout-hackery - of the pgf externalization bite each other. - \begin{Form} must come before the shipout hackery of pgf. - 3. \includegraphics does not preserve PDF forms. - - the interrupt bounding box feature should still update the data bounding box. Otherwise, transformations may fail. @@ -399,21 +1090,663 @@ X Fix the scaling estimations. X verschiebung des ylabels ist komisch, wegen der rotate option ++ that first/last coord detection doesn't work for 3D ------------------------------------------------------------- FEATURES ------------------------------------------------------------- +- \addplot coordinates {\macro}; + +- precise width calculation idea: + - Problem: total width depends on width of axis descriptions + - width of axis descriptions depends on position of axis descriptions + - position of axis descriptions depends on width of axis + - width of axis depends on width of axis descriptions + -> non-linearly coupled system. + - Idea: introduce a loop. + - details: + 1. place axis descriptions + the axis rectangle into a box. + 1.1 Measure box'es width, throw it away if it is too bad. Keep it and stop iteration otherwise. + 2. recompute the complete scaling. + 3. go back to step 1.) and iterate + -> one or two iterations should be enough . + -> it's not necessary to recompute the prepared and stored plots. Just keep them in main memory until the scaling is fixed. + +- bar plots: + - bar interval plot handler which *assumes* uniform distances. This allows to eliminate the last, superfluos grid point (because it can be generated automatically as replication x_last + h for known h) + - in fact, I could also implement + x_last + h_last + and introduce a new name like 'bar interval*' or something like that + +- Mails from Stefan Ruhstorfer: + 2. + Gruppierte Säulendiagramme sind nach meinem Wissenstand nur dann möglich wenn man in der Axis-Definiton die Bedindung ybar angibt. Ich finde diese Ausrichtung sehr unflexible, da ich sehr oft über das Problem stolpere, dass ich in meinem gruppierten Säulendiagramm noch eine waagrechte Linie oder ähnlichs einzeichnen möchte um z.B. meine obere Toleranzgrenze einzuzeichnen. Bis jetzt mache ich das über den normalen \draw Modus, was auch ausgezeichnet funktioniert. Jedoch habe ich dann das Problem, dass ich keinen schönen Legendeintrag mehr bekomme. Hier häte ich 2 Vorschläge. Zum einen die Legende "freier" zu gestalten. Also so, dass man beliebig (ggf. auch ohne Plot) ein Legendenelement hinzufüen kann und vllt. noch das zugehörige Symbol festlegen kann. (Bis jetzt habe ich das Problem, das ich mit tricksen zwar meine Obere Tolerangrenze in die Legende bekomme, dann jedoch mit einem Säulenzeichnen davor). + Der andere Vorschlag ist, dass Säulendiagramm anders zu definiern. So das ich auch noch einen Plot hinzufügen kann, der mir eine waagrechte Linie ohne zu tricksen einzeichnen lässt. + + + 3. Eine Gruppierung von stacked bars ist nach meinem Wissen nicht möglich. Es ist zwar schwer sich ein Anwendungsgebiet dafür vorzustellen, aber wenn sie danach mal suchen (speziell im Excelbereich) werden sie sehen, dass viele Leute so eine Funktion benutzen. + + -> siehe auch folgemails mit Beispielskizzen + -> beachte: Fall 2.) erfordert mehr arbeit als lediglich 'line legend', weil ybar ja den koordinatenindex verarbeitet! + +- 3D + axis line variants: someone might prefer GRID LINES as for the boxed case + combined with axis line=left... + +- the table package uses a lot of logs -- but it can't change the log basis. + +- automatically choose a predefined scaling style depending on width/height (?) + +- my elementary data structures always use \string to support macros as data structure names. I fear this might be ineffective. + 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>' + the command should assign '\pgfplotsretval' + ++ It would be a valueable addition if the external lib would be available for the next stable release. + ++ the scatter/classes feature needs a legend. + +- the following keys should process their argument with \pgfmathparse: + - [xyz]tick, + - min/max + - tickmin/max + - meta min/max + - domain/ y domain, + - error bar arguments, + - without FPU: width/height/ view + -> check optimizations of the math parser! + -> check if I can activate the FPU during the survey phase! + +- check y tick scale label for 2nd y axis + ++ provide a '3d box' boolean which draws the full box. + -> should use the correct drawing sequence (foreground/backgraound) + -> should use the decoration things + ++ there is no possibility to provide a background color for the axis only + (should be a fill/draw style for the clip area). + ++ -> perhaps 'plot box aspect ratio=<x> <y> <z>' ? + And I still have the stretch-to-fill thing as in matlab. + ++ finish the 'unbounded coords=jump' method. + Ideas: + + mesh plots should use a special method here: + + they should proceed as usual - and eliminate complete patches + with special treatment. + + the use of shader=interp should throw an exception in case of + unbounded coords. + ~ all other plots work reasonably well with it, I suppose. + + plot graphics should throw an exception as well. + + should the user filter results be filtered by 'unbounded coords' as + well?? They are not unbounded - they have been discarded... + +- idea to improve rel. accuracy: do not simply invoke 'pgfmath@basic@...' but + allow an arbitrary suffix. Maybe one could allow to use the FP package. + ++ reverse axis=true ideas for 3D: + + this flips the normal vector in some sense. Since the "foreground" + algorithm simply queries the sign of the normal vectors, I only need to + check for a "-1" in the right places. If I am not mistaken, changes in the + following components should be enough: + - decision which is foreground/background + - 'ticklabel cs' and 'rel axis cs' + -> these may require a design decision! What does the "0" coordinate + mean: the lower limit or the lower part of the figure? + ++ z buffer implementation ideas: + + reverse: is already implemented + + reverse x: + A_ij := a_{i,n-j} + for ordering=rowwise: trivial: reverse rowwise + for ordering=colwise: same technique as for transposal: collect + colvectors in fast applist; reverse this colvectors + + reverse y: the same with exchanged roles. + + auto: I need to know: + + How are the coordinates sorted? + If ascending in x and ascending in y, everything is ok. Otherwise, I + need to remember signs. + -> it should suffice to check the FIRST and LAST coordinate to get + these signs! + + If both are ascending: I can decide per axis if coordinate reversal is + necessary: + If "0vv" is background -> ok, change nothing. + If "0vv" is foreground -> reverse in x. + The same should also work for y -> allows very fast decision. + + ++ I have the following request. Is it possible to also provide a domain +key for file and table plots. I have a file containing data points +where only the points in a certain range shall be plotted. I first +thought that filters might be a solution, but it seems that they apply +to the whole axis, not only to one specific plot. + ++ I have a suggestion for the next release of the pgfplots package. +Now it seems to be so, that the major tick lines are drawn before the minor tick +lines, which can lead to unwanted results, if somebody redefines the color of +the minor grid only. So it would be better to draw then the other way round. +Does somebody else agree? +- that's not solved yet! Try it out for grid lines! + ++ the UI to provide point meta is complicated. + Why + point meta=explicit,table/meta={<colname>} + instead of + point meta=\thisrow{<colname>} ?? + [ ADDED SANITY CHECK AND ERROR MESSAGE] + + The reason is technical: My code separates the table reading and the + coordinate processing. I'd like to discard this separation.... but I hesitate + to do so because this might lead to scoping problems... + Work-around idea: check if the '\thisrow' macro occurs and set then + 'explicit,table/meta=...' accordingly. + +- log plots: minor tick num would be useful here! If tick labels are placed at + '1e-5, 1e0', minor tick num= 4 would lead to the minor tick lines at + '1e-4,1e-3,1e-2,1e-1' which is useful. + So:allow minor tick num for log axes. + -> + need to adjust the check for "uniform log ticks" + +- is there a way to get the current row/col index during \addplot? + +- plot shell: + - It would be nice if the standard shell interpreter could be replaced. + Idea: + \pgfkeys{/pgfplots/plot shell/interpreter/.code 2 args={sh #1 > #2}} + then in the code + \pgfkeysvalueof{/pgfplots/plot shell/interpreter/.@cmd}{#1.sh}{#1.out}\pgfeov + - the \pgfshell macro is quite general and could be added to pgf (as + suggested by you, Stefan). However, this would also need modifications in + tikz.code.tex to get some sort of high-level user interface. + I find plot shell very useful, and it could be added easily. My + suggestion: + Either write a high level user interface for tikz or rename the command + to \pgfplotsshell and put it into pgfplotscoordprocessing.code.tex. + In the meantime, I added it to pgfplotscoordprocessing.code.tex (bottom). + - there is a potential difficulty with the '\addplot table shell' command + (which is a good solution!): the semicolon in this routine will have a + fixed catcode. But packages like babel with french language will change it + to active, so french people can't use \addplot table shell. The solution + is technical and I am not proude of my own anyway... we'll just have to + think about one. + - documentation for the 'table shell' feature is missing yet. + - I am not sure if the replication of /tikz/prefix and /tikz/id is helpful + or confusing.... + + + ++ provide a possibility to get the maximum tick width (for use in ticklabel cs) + +- > Is it possible to shade the area between two curves, using pgfplots, such as + > in this example: http://www.mathworks.com/matlabcentral/fileexchange/13188 + > The only shading I could find is between one curve and the x axis... Shading + > between curves seems to be possible, but only with stacked curves. Is is + > possible to disable stacking somehow, but keep the \closedcycle behavior? + ++ provide a possibility to draw gaps. Maybe using nan or inf coordinates? + Currently, NaNs and infs are skipped and pgfplots simply interpolates over + the gaps. Perhaps it would be better to explicitly form a gap? I am not sure + about that, but it appears to be a good idea. Requires a lot of special + handling + ++ provide a 'y variable' key? + ++ provide other log bases + ++ implement colorbars. I have a running prototype; it just needs some tuning. + Ideas: + + place it as a separate axis besides the original one. + + make sure that named nodes like 'current axis' stay correct - as if there + was no extra axis. + + provide all required variables locally in pgfkeys - the meta limits and + style arguments etc. + + I need to communicate: + + the current color map, + + styles for ticks, tick labels and axis lines (?) + (at least the tikz ones?) + + create a style for the new axis. + +- re-implement sampling loops. I should discard the compatibility with \foreach + internally in order to gain accuracy! Maybe it is necessary to invoke + different loops - one for tikz \foreach (samples at) and one "standard" + sampling routine. + +- 3D: assume default plot type when used with \addplot3 without plot style + (perhaps a special cycle list) + + ++When working with markers on the plots, the nomenclature is inconsistent. There +is 'mark size', 'mark=*' and 'only marks', but 'no markers'. + ++I created several cycle lists to be consistent in different types of plots. For +example I have a cycle list with markers and no lines for raw data points and a +cycle list with only lines in corresponding color. Now if I want to have raw +data points and fits in one axis, I cannot use these. Ok, I could make a +cyclelist where raw data and fit styles take turns, but this would break down +when I have more than one fit for a set of raw data. This is probably something +that has to go into pgf, but would it be possible to add a easy way ++ to switch to different cycle list between two addplots, +- and to navigate in it (go to a specific position in the cycle list, go n steps back/forth)? + ++When I first tried to combine plots with only symbols and plots with only a +line in one plot, I had difficulties to figure out how to do it. Having worked +with pgf before, I intuitively tried to activate no marks/only marks for the +whole axis and then override it explicitly for some plots, by adding [only +marks/no marks] to addplot. + ++I would find it convenient, if there was a key to indicate legend placement, +for example 'legend position=south west' as shorthand for 'legend +style={at={(0.05,0.05)},anchor=south west}' or something similar. + + +- replace \pgfpointscale with a 'q' version -> it invokes the expensive math parser. + +- optimization ideas: + - pgfmultipartnode evaluates every anchor twice + - implement a cache for expensive, repeated math operations like 'view' + directions or common results of 1/||e_i|| . + - search for unnecessary math parser invocations; replace with 'q' versions + if possible. + - implement a hierarchical generalization of the 'applist' container (a tree + applist of arbitrary length) + - eliminate the deprecated 'non-legend-option' processing. + - remove the different (empty) paths of the axis node -- it appears they are + not necessary and waste only time and mem. + - try implementing an abstract 'serialize' and 'unserialize' method - it + might be faster to re-process input streams instead of generating + preprocessed coordinate lists. + - try to reduce invocations of pgfkeys + - optimize the filtered pgfkeys invocations - the filter is slower than + necessary! + - eliminate the 'veclength' invocations for single axes - they can be + replaced with "inverse unit length * (max-min)" + - the key setting things can be optimized with \pgfkeysdef + - create the /pgfplots/.unknown handler (.search also=/tikz) once and remember it. + - the (new) tick label code might be very expensive: + - check for (unnecessary) calls to \pgfpointnormalised -- the normal + vectors are already normalised! + - check the cost for bounding box size control of the tick labels -- + maybe this can be optimized away if it is not used. But this decision + is not easy. + ++ 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 + 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 + and can do something. One application would be to place nodes "above" of the + low level coordinate and use number formatting routines to display the number. + This shouldn't be difficult (with the exception of logs ... or user + transformations... hm.). + -> think about it. + -> log can be visualized with 10^{<tick>} as before! + -> the 'inv trafo' can be applied if and only if needed. Idea: provide macros + like '\x', '\y' and '\z'. This should do it. + +- use the new \pgfplotspointoutsideofticklabelaxis things to place axis labels. + -> this needs a further variant which allows 'relative' axis coordinates + (0=lower limits, 1=upper limit and everything between) + +- I need a clean interface to distinguish between R^1 -> R^3 and R^2 -> R^3 + visualization. + Maybe a boolean 'matrixinput' or something like that? + -> the 'mesh' plot handler is also useful for line visualization! + - the '/pgfplots/mesh' key could set matrixinputtrue + - a style 1dmesh or so could set the plot handler and disable meshmode? + Of course, I could also try to evaluate the 'rows' and 'cols' values. + If cols=1, I have line visualization. + ++ allow changes to `legend image code' in plot styles. Maybe the 'legend image + code' or some other preparation commands can be remembered explicitly such + that they are set before 'legend image code' is already running? + +- legends need a better key path to process pgfplots plot handlers. ++ I need legends for mesh/surface plots. + +- the tick anchor=auto feature could work like this: + - "use paraxial whenever possible - unless the user requests "tikz" + explicitly or implicitly". + - "explicit" request: the user says "tick anchor=tikz". + - "implicit" request: the user says "anchor=..." for a tick label. + - realization: + - use \scope to set the tick label styles, overwrite + '/tikz/anchor' inside of this scope's pgfkeys statement. + -> that doesn't work. I NEED to adjust 'every node'. + - move the processing of 'tick anchor' inside of that scope + - effect: 2D axes will also be processed by means of 'paraxial' (unless the + user doesn't want it). + -> reversed axes work automatically! + ++ provide the axis bounding box as coordinate system (for description placement). + + +- provide a \pgfplotspathcube command as generalization from the cube marker. + The cube command should work similar to pathrectangle or rectanglecorners. + +- write a public math interface which provides access to axis internals like + limits, the 'dimen-to-coordinate' method and so on. + -> it might be useful to use pgfmathparse for any numerical input argument as + well. + ++ write public interface \pgfplotsdepthofxyz#1#2#3 +- consider renaming that one to pgfmath... or pgfplotsmath... ? + ++ reverse legend + -> CF: implementation of Tom Cashman per mail + +- what about in-text-input of tables like + \pgfplotstableread\data{<data>....<data>}{\macro} + \pgfplotstableread\data{<data>....<data>} to listener \listener + +- I have just added '* expr' for plot table. + ideas todo: + + implement it for plot table structure as well, + - document plot file such that users know how to add expressions, or, even + better, automatically switch to plot table if someone uses x expr.. + +- maybe some sort of 'point meta=map' would be interesting. + The idea is to provide a mapping + (x,y,z,singlemeta,additionalinfo) -> f_1,f_2,f_3,f_4,f_5,...,f_n + and each f_n has a name and a value. + The additionalinfo could be further rows in a table or the current plot + context. Then, each f_i could be a symbol, maybe a number or something like + that. There should be one designated f_i which is used as "the" cdata source + and which is mapped to [0,1000]. + +- optimize the z buffer=sort impl of mesh mode: use preallocation (doesn't yield + much, but at least a bit) + ++ it could be interesting to provide customizations to the cube marker. For + example different lengths for each side... could be used as basis for a 3D bar + plot implementation. + +- there are applications in which BOTH untransformed meta AND transformed meta + are required. In this case, the untransformed meta should be provided in a + more convenient way - perhaps as fixed point number? + +- in scatter point public interface: it would be interesting to know if we are + currently processing the first/last coordinate. is that information available? + ++ write default styles for "string coordinates" which maps a set of +user defined strings somehow into a numeric range (using a simple +dictionary) + +- It is certainly possible to write some sort of CELL-BASED 'mesh/surf' shader - + a combination of 'flat corner' and cell based rectangles: + - every coordinate denotes a CELL instead of a corner, + - the "shader" maps the cdata into the colormap to determine the cell color + - details? + - to get well-defined cells, I have to enforce either a non-parametric + lattice grid or do a LOT of additional operations (?). + - alternative: define N*M cells by N+1 * M+1 points. + - perhaps a combination of both? + -> that's more or less the same as 'flat mean' up to the further + row/column pair + - it would be generally useful to have an "interval" or "cell" mode: + the idea is that every input coordinate defines an interval (1d) or a cell + (2d). To define the last cell, one needs to add one "mesh width" somehow. + I just don't know where: + - the artificial cell should be processed with the normal streams - + including limit updates, stacking etc. + - the artificial cell needs to know when the end-of-stream occurs. + For 1d plots, that may be possible. For 2D plots, this information + requires a valid 'cols' key. + - I suppose it would be best to patch @stream@coord.. at least for the + 'cell' mode. + - Idea: + - the \pgfplots@coord@stream@coord implementation realizes the + cell-mode: after every 'cols' coordinate, a further one is + replicated. This needs the "last mesh width". + Furthermore, it needs to accumulate a row vector, the "last row". + This last row is need during stream@end to replicate the further + row: + - the \pgfplots@coord@stream@end implementation has to realize the + last step of cell mode: the replication of a further row. It also + has to realize the implementation of 'interval' mode (replication + of last coordinate). + My idea is to simply use an applist for this row accumulation. The + format should be compatible with \pgfplots@coord@stream@foreach@NORMALIZED. + That doesn't produce problems, even when the end command is invoked within + a foreach@NORMALIZED loop - because the loop has already ended. + + + + +- I have a funny idea to replace the memory intensive and slow TeX based data + structures: I could write coordinate streams into a file like LaTeX's .aux + file - and re-read it. The file performs the coordinate loop automatically in + such a case. Key question: what's more expensive: \input or the optimized + macro append? There may be an even-point at which one should switch the low + level data structure. + - One could introduce some kind of in-macro caching: write to file every 100 + elements or so. + This would be the applistX with the same L1 and L2 caches - but the main + memory would be a file instead of a macro. + - maybe it is sufficient to use concatenate up to N three-level-deep + applistX, each with a fixed size? This should work as well. The global + number of macros required for such an implementation would be 3*N. If each + macro contains several thousand points, this would be better than nothing - + and simpler than a tree. But it doesn't have good asymptotics, I agree. + + + ++ pdf supports REAL lattice shadings! See pdf reference 1.7, section 4.6.3. + It is possible to write the coordinates on a lattice and colors for each coordinate; + resulting in a correctly interpolated shading. I suppose this uses a z buffer. + The only problem: it requires binary integer input. The integers are then + mapped linearly into the real space using the /Decode array. + If I could somehow write binary data into pdf streams, this would work + properly. + + Notes to finish that thing: + - the plot expression sampling could automatically respect the 'z buffer + emul' -> and clear the variable afterwards (optimization) + + finish low level interface + + write ps driver + + + + +- 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 + [-16384,16384] -> <range for N bytes> + properly, i.e. it is just an integer division. The resulting integer can be + encoded using the available linear map functionality. + + ++ is there a (small?) possibility to write an efficient z buffer? To order the + drawing operations for mesh/surf plots? + -> Idea: for surface plots, it should be completely sufficient to start + drawing at the correct edge; in the correct direction. + Thus, the required operations to get a correct "z buffering" is either + + to reverse the sequence (i.e. to reverse rows and cols), + + to reverse the rows + simple a posteriori impl: iterate through sequence, pushfront every + row element. When row complete: pushback onto the final list. + + to reverse the cols + simpel a posteriori impl: iterate through sequence, pushback every + row element. When row complete: pushfront onto final list. + + ok, I have implemented sorting and depth information. + Ideas: + + for scatter plots: simply sort coordinates, + - for 3d bar plots (to be implemented): sort by (x,y,0) coordinates + + for (1d/2d) mesh plots: sort fragments (lines or rectangular + patches) according to the depth information of one corner, + + for any single-colored plot handler (lineto, curveto etc): to NOT + change the sequence. + -> perhaps I can return both, the sorted AND the unsorted sequence + if one has markers and single-colored plot handlers. + + don't use the enumeration pattern here; use '\let' to set the z + buffering technique (if possible). + ++ provide better styles for 3D plots: + + enlarge [xy] limits=false, + + view={45}{-30} + ++ Ideas for 3D axes: + + I could introduce '\addmesh' (or a 'mesh=true|false' option). + -> this activates R^2 -> R^3 visualisation. + -> \addplot is then always R^1 -> R^{2,3} + + only \addplot3 {<expr>} is different: it should default to (x,y,<expr>) + using a mesh. + + mesh input: + + for plot expression: sample a matrix + + for coordinates, file, table: + + describe how the linear sequence shall be mapped into a matrix + + requires the matrix' size and a flag 'ordering=rowwise|colwise' + + in principle, the matrix size is controlled by the samples key. + But since we are describing a mapping here, we should (maybe) + introduce a further key like |resulution={x}{y}| ... + + I need a |samples y| key anyway. + + visualization: + + case 'only marks': easy, just as before. + + all other cases: + + visualizations like surface and mesh are relatively simple: + we can iterate through the matrix (for example row-by-row) + and we ONLY need to access the CURRENT AND LAST ROW to + draw the required things. + -> Idea: provide an abstract datastructure which provides fast + access and efficient storage for the last visited row! + The best would be an array, but I should keep in mind that + arrays may be too inefficient with respect to TeX storage. + + I can implement 'flat shading' (piecewise constant). Idea: + + use rectangular elements + + query the colormap for one of the four corner points + + simply draw+fill the element with that color. + + framework: either the same as for scatter plots, or maybe + I can use the pgf basic- or system layer for the color + commands. This is potentially faster. + ++ Notes for how to finish the 3D axes visualisation: + + a 3D axis consist of several different parts (all of them are now more or + less ready). + They are: + + three axis vectors which determine the 2D projection. + + Input methods: + + |view| key (preferred) + X explicit |x,y,z| vectors + X |x,y,z| vectors given in the correct relative size. + -> simply scale them uniformly to get the desired width and + height + + A method to scale those axis vectors to get the desired dimensions. + + A decision for how to plot the axes: + + a complete box. + + only three surfaces visualized (the "back" of the axes) + + A decision which of the (available!) axis lines shall be used for + tick lines and tick labels. + Of course, this depends on the choice in (3.). + Input methods: + + automatic placement. This is the preferred method. + this requires + a) a decision which axis line gets the tick labels + b) a decision whether tick labels are "right of" or whatever + the chosen axis line. + X user defined placement: the user EXPLICITLY provides the desired + axis. + X The point (4b) above shall be modifyable by a user interface. + + An easily usable user interface to place axes descriptions like + labels and title. + Possible choices: + + Placement relative to axes vectors. + + Placement relative to a two-dimensional coordinate system, + relative to the VIEWPORT ("left of figure", "right of figure", + "above figure") + + Placement "parallel" to the axes which got tick labels + + "really" parallel? -> badly rotated text + + just "near" the respective axis line? + + - Some more implementation notes: + + If one of the 2D x,y,z vectors has length 0, the respective axes + should be hidden. + + a normal 2D axes should be considered to be an efficient special case + of a three dimensional axes - hide the special treatment as far as + possible. + + the routine which computes default tick positions needs + veclength*(max-min). Verify that. + + provide new keys: + + [xyz]ticklabel anchor=auto,paraxial,tikz + + [xyz]ticklabel dist=<dimen> + + with 'auto': + + non orthogonal axis => same as paraxial + + 3D => same as paraxial + + all other cases => same as tikz + + with 'paraxial': + + my new stuff (with the '*dist' keys as parameters) + + with 'tikz': + + as before: 'at='<tick position> and the anchor determines the + alignment. + + I still need anchors for 'paraxial' + + for axes labels: + Idea: use Tikz's '\node[pos=0.5]' feature + + prepare two coordinates and a path (user configurable) which + connects them + + place the label on the path, for example using pos=0.5 + + the path could be (depending on the tick label position which is + either LEFT or RIGHT) -- |- -| or something like that. + + Ideas how to get those axes / surfaces which are on the back/front of + the 2d projection: + + I need the 3d (!) view direction. For 'view=', the 3d view + direction is directly available, for explicitly provided axis + vectors, it should be possible to compute it using cross products + and embedding in 3d (at least I hope so) + + now, given the 3d view direction and the three 3d axis vectors, I can + compute scalar products to check whether the view axis and the + axis vector point into the same direction. If I am not mistaken, + the following case distinctions hold: + v * e_x > 0 => the surface attached at the lower end of e_x is + FRONT, the surface attached at the upper end of e_x is BACK. + This should hold for e_y and e_z as well. Furthermore, the 3d axis + vectors are just unit vectors (if I suppose that only the view is + rotated) + + given the flags "FOREGROUND=[0|1]" for each axis line / axis + surface, I can also deduce + + which lines shall be drawn (or, in case of a complete box, + *when* they shall be drawn - as foreground or as background), + + which lines shall contain tick labels + + which lines shall contain axis labels + + the FPU uninstall command can be assembled ONCE (globally). No need to do that multiple times. -- What about something like '/pgfplots/table/x expr={<math expression>}' ? ++ What about something like '/pgfplots/table/x expr={<math expression>}' ? -> I could still use the lazy eval framework of pgfplotstable, i.e. \thisrow{} commands, \pgfplotstablerow, \pgfplotstablecol etc. The \prevrow and \nextrow features won't be possible (?) - improve support for multiple ordinates -- improve support for negative axes +- improve 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 plot expression + accuracy @@ -444,7 +1777,7 @@ FEATURES - define a 'cycle list' style which simply inserts different colors into the predefined style (thus, markers are fixed, colors vary). One could also think about a complementary style. - -> even better: I could prodive up to three different lists which can be + -> even better: I could provide up to three different lists which can be combined. Example: colorlist, markerlist, linespeclist -> iterate through all possible combinations! @@ -501,27 +1834,27 @@ X the coordinate preparation routines should assign global registers. This would - provide 'only each nth coordinate' or so as style on top of 'x filter'. -- 3D axes: my axis is "heavy weighted". ++ 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" + + 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 + + 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 + + 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 + + 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 + + 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 + + automatically decide WHICH axis lines shall be drawn. + + see http://mathworld.wolfram.com/EulerAngles.html + implement simply style 'scatter classes'. + sanity checking feature: try if 'pgfmathfloattofixed' results in a known @@ -676,12 +2009,11 @@ X perhaps I can use pdf line annotations to improve clickable lib? Those family macros can be optimized (sure ?). - provide access to axis limits and data bounding box. - -- It would be useful to get access to axis coordinates, for example in 'circle (XXX)' + It would be useful to get access to axis coordinates, for example in 'circle (XXX)' + axis equal option -- consider 'plot image[xmin=,xmax=,ymin=,ymax=] {<graphics>}; ++ consider 'plot image[xmin=,xmax=,ymin=,ymax=] {<graphics>}; -> load external plot image!? Only useful for matlab, if matlab would allow 100% control over bounding box. Unfortunately, it doesn't. |
