summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-07-16 23:47:14 +0000
committerKarl Berry <karl@freefriends.org>2010-07-16 23:47:14 +0000
commit0c242425bcb89cc3af3064b8b895608a7f5ec3bb (patch)
treec9e2e2a0cd90b875325b6ef0cc06edada1b5f4ec /Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
parenta77f52d8c904326838bc0523faffdc79bdff0f6e (diff)
pgfplots 1.4 (14jul10)
git-svn-id: svn://tug.org/texlive/trunk@19488 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex138
1 files changed, 116 insertions, 22 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
index 4af602d4fd8..2f4884e4cff 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
@@ -361,30 +361,54 @@ one may want to plot `|dof|' versus `|L2|' or `|dof|' versus `|Lmax|'. This can
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
-or
+or, for the |Lmax| column, using
\begin{codeexample}[code only]
\begin{tikzpicture}
\begin{loglogaxis}[
xlabel=Dof,
- ylabel=$L_infty$ error]
+ ylabel=$L_\infty$ error]
\addplot table[x=dof,y=Lmax] {datafile.dat};
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
-Alternatively, you can load the table \emph{once} and use it \emph{multiple} times:
+It is also possible to provide the data inline, i.e.\ directly as argument in curly braces:
\begin{codeexample}[code only]
-\pgfplotstableread{datafile.dat}\loadedtable
+\begin{tikzpicture}
+\begin{loglogaxis}[
+ xlabel=Dof,
+ ylabel=$L_\infty$ error]
+\addplot table[x=dof,y=Lmax] {
+ dof L2 Lmax maxlevel
+ 5 8.31160034e-02 1.80007647e-01 2
+ 17 2.54685628e-02 3.75580565e-02 3
+ 49 7.40715288e-03 1.49212716e-02 4
+ 129 2.10192154e-03 4.23330523e-03 5
+ 321 5.87352989e-04 1.30668515e-03 6
+ 769 1.62269942e-04 3.88658098e-04 7
+ 1793 4.44248889e-05 1.12651668e-04 8
+ 4097 1.20714122e-05 3.20339285e-05 9
+ 9217 3.26101452e-06 8.97617707e-06 10
+};
+\end{loglogaxis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent Inline table may be convenient together with `|\\|' and |row sep=\\|, see below for more information.
+
+Alternatively, you can load the table \emph{once} into an internal structure and use it \emph{multiple} times:
+\begin{codeexample}[code only]
+\pgfplotstableread{datafile.dat}\loadedtable % use any custom name in place of `\loadedtable'
...
-\addplot table[x=dof,y=L2] from \loadedtable;
+\addplot table[x=dof,y=L2] {\loadedtable};
...
-\addplot table[x=dof,y=Lmax] from \loadedtable;
+\addplot table[x=dof,y=Lmax] {\loadedtable};
...
\end{codeexample}
-I am not really sure how much time can be saved, but it works anyway. As a rule of thumb, decide as follows:
+I am not really sure how much time can be saved, but it works anyway. The |\pgfplotstableread| command is documented in all detail in the manual for \PGFPlotstable. As a rule of thumb, decide as follows:
\begin{enumerate}
- \item If tables contain few rows and many columns, the |from |\meta{\textbackslash macro} framework will be more efficient.
+ \item If tables contain few rows and many columns, the \meta{\textbackslash macro} framework will be more efficient.
\item If tables contain more than~$200$ data points (rows), you should always use file input (and reload if necessary).
\end{enumerate}
+Occasionally, it might be handy to load a table, apply manual preparation steps (for example |\pgfplotstabletranspose|) and plot the result tables afterwards.
If you do prefer to access columns by column indices instead of column names (or your tables do not have column names), you can also use
\begin{codeexample}[code only]
@@ -394,24 +418,29 @@ If you do prefer to access columns by column indices instead of column names (or
Summary and remarks:
\begin{itemize}
- \item Use |plot table[||x||=|\marg{column name}|,||y||=|\marg{column name}|]| to access column names. Those names are case sensitive and need to exist.
- \item Use |plot table[||x index||=|\marg{column index}|,||y index||=|\marg{column index}|]| to access column indices. Indexing starts with~$0$. You may also use an index for~$x$ and a column name for~$y$.
- \item Use |plot table[||header||=false] |\marg{file name} if your input file has no column names. Otherwise, the first non-comment line is checked for column names: if all entries are numbers, they are treated as numerical data; if one of them is not a number, all are treated as column names.
+ \item Use |\addplot table[||x||=|\marg{column name}|,||y||=|\marg{column name}|]| to access column names. Those names are case sensitive and need to exist.
+ \item Use |\addplot table[||x index||=|\marg{column index}|,||y index||=|\marg{column index}|]| to access column indices. Indexing starts with~$0$. You may also use an index for~$x$ and a column name for~$y$.
+ \item Use |\addplot table[||x expr=\coordindex,y=|\marg{column name}|]| to plot the coordinate index versus some $y$ data.
+ \item Use |\addplot table[||header||=false] |\marg{file name} if your input file has no column names. Otherwise, the first non-comment line is checked for column names: if all entries are numbers, they are treated as numerical data; if one of them is not a number, all are treated as column names.
\item It is possible to read error coordinates from tables as well. Simply add options `|x error|', `|y error|' or `|x error index|'/`|y error index|' to \marg{source columns}. See section~\ref{sec:errorbars} for details about error bars.
\item It is possible to read per point meta data (usable in |scatter src|, see page~\pageref{pgfplots:scatter:src}) as has been discussed for |plot coordinates| and |plot file| above. The meta data column can be provided using the |meta| key (or the |meta index| key).
- \item Use |plot table[|\meta{source columns}|] from |\marg{\textbackslash macro} to use a pre--read table. Tables can be read using
+ \item Use |\addplot table[|\meta{source columns}|] |\marg{\textbackslash macro} to use a pre--read table. Tables can be read using
\begin{codeexample}[code only]
\pgfplotstableread{datafile.dat}\macroname.
\end{codeexample}
- The keyword `|from|' can be omitted.
+ If you like, you can insert the optional keyword `|from|' before |\macroname|.
- \item The accepted input format of those tables is as follows:
+ \item The accepted input format of tables is as follows:
\begin{itemize}
+ \item Rows are separated by new line characters.
+
+ Alternatively, you can use |row sep=\\| which enables `|\\|' as row separator. This might become necessary for inline table data, more precisely: if newline characters have been converted to white spaces by \TeX's character processing before \PGFPlots\ had a chance to see them. This happens if inline tables are provided inside of macros. Use |row sep=\\| and separate the rows by `|\\|' if you experience such problems.
+
\item Columns are usually separated by white spaces (at least one tab or space).
If you need other column separation characters, you can use the
- \declare{col sep}\pgfmanualpdflabel{/pgfplots/table/col sep}{}|=|\mchoice{space,tab,comma,colon,semicolon,braces}
+ \declare{col sep}\pgfmanualpdflabel{/pgfplots/table/col sep}{}|=|\mchoice{space,tab,comma,colon,semicolon,braces,\&,ampersand}
option which is documented in all detail in the manual for \PGFPlotstable\ which is part of \PGFPlots.
\item Any line starting with `\#' or `\%' is ignored.
@@ -425,9 +454,18 @@ Summary and remarks:
\index{table@\textcolor {gray}{\texttt {plot}}\texttt { table}!Unbalanced Columns}%
\end{itemize}
\item It is also possible to use \textbf{mathematical expressions} together with `|plot table|'. This is documented in all detail in section~\ref{pgfplots:addplot:table:expr}, but the key idea is to use one of |x expr|, |y expr|, |z expr| or |meta expr| as in `|plot table[||x expr=\thisrow{maxlevel}+3,y=L2]|'.
- \item The enhanced column generation methods provided by \PGFPlotstable\ are also accessible for plots, see the \PGFPlotstable\ manual section ``Postprocessing Data in New Columns''.
+ \item The \PGFPlotstable\ package coming with \PGFPlots\ has a the feature ``Postprocessing Data in New Columns'' (see its manual).
+
+ This allows to compute new columns based on existing data. One of these features is |create col/linear regression| (described in Section~\ref{sec:linefitting}).
+
+ You can invoke all the |create col/|\meta{key name} features directly in |\addplot table| using
+
+ |\addplot table[x={create col/|\meta{key name}|=|\meta{arguments}|}]|.
+
+ In this case, a new column will be created using the functionality of \meta{key name}. This column generation is described in all detail in \PGFPlotstable. Finally, the resulting data is available as $x$ coordinate (the same holds for |y=| or |z=|).
+
+ One application (with several examples how to use this syntax) is line fitting with |create col/linear regression|, see Section~\ref{sec:linefitting} for details.
- In this context, you should consider using the key |read completely|, see below.
\item Technical note: every opened file will be protocolled into your log file.
\end{itemize}
\end{addplotoperation}
@@ -469,17 +507,51 @@ The following list of keys allow different methods to select input data or diffe
table/meta index=\marg{column index}}
These keys define input sources for per point meta data. Please see page~\pageref{pgfplots:scatter:src} for details about meta data or the documentation for |plot coordinates| and |plot file| for further information.
\end{pgfplotsxykeylist}
-\begin{key}{/pgfplots/table/col sep=\mchoice{space,tab,comma,semicolon,colon,braces} (initially space)}
+
+
+\begin{pgfplotskey}{table/row sep=\mchoice{newline,\string\\} (initially newline)}
+ Configures the character to separate rows.
+
+ The choice \declaretext{newline} uses the end of line as it appears in the table data (i.e.\ the input file or any inline table data).
+
+ The choice \declaretext{\string\\} uses `|\\|' to indicate the end of a row.
+
+ Note that \declaretext{newline} for inline table data is ``fragile'': you can't provide such data inside of \TeX\ macros (this does not apply to input files). Whenever you experience problems, proceed as follows:
+ \begin{enumerate}
+ \item First possibility: call |\pgfplotstableread|\marg{data}|\yourmacro| \emph{outside} of any macro declaration.
+ \item Use |row sep=\\|.
+ \end{enumerate}
+ The same applies if you experience problems with inline data and special |col sep| choices (like |col sep=tab|).
+
+ The reasons for such problems is that \TeX\ scans the macro bodies and replaces newlines by white spaces. It does other substitutions of this sort as well, and these substitutions can't be undone (maybe not even found).
+\end{pgfplotskey}
+
+\begin{key}{/pgfplots/table/col sep=\mchoice{space,tab,comma,semicolon,colon,braces,\&,ampersand} (initially space)}
Allows to choose column separators for |plot table|. Please refer to the manual of \PGFPlotstable\ which comes with this package for details about |col sep|.
\end{key}
-\begin{key}{/pgfplots/table/read completely=\marg{true,false} (initially false)}
+\begin{key}{/pgfplots/table/read completely=\marg{auto,true,false} (initially auto)}
Allows to customize \verbpdfref{\addplot table}\marg{file name} such that it always reads the entire table into memory.
This key has just one purpose, namely to create postprocessing columns on-the-fly and to plot those columns afterwards. This ``lazy evaluation'' which creates missing columns on-the-fly is documented in the \PGFPlotstable\ manual (in section ``Postprocessing Data in New Columns'').
+ The initial configuration |auto| checks whether one of the keys |table/x|, |table/y|, |table/z| or |table/meta| contains a |create on use| column. If so, it enables |read completely|, otherwise it prefers to load the file in the normal way.
+
\paragraph{Attention:} Usually, \verbpdfref{\addplot table} only picks required entries, requiring linear runtime complexity. As soon as |read completely| is activated, tables are loaded completely into memory. Due to datastructures issues (``macro append runtime''), the runtime complexity for |read completely| is $O(N^2)$ where $N$ is the number of rows. Thus: use this feature only for ``small'' tables\footnote{This remark might be deprecated; many of the slow routines have been optimized in the meantime to have at least pseudo-linear runtime.}.
\end{key}
+\begin{key}{/pgfplots/table/ignore chars=\marg{comma-separated-list} (initially empty)}
+ Allows to silently remove a set of single characters from input files. The characters are separated by commas. The documentation for this command, including cases like `|\%,\#,\ |' or binary character codes like `|\^^ff|' can be found in the manual for \PGFPlotstable.
+
+ This setting applies to |\addplot file| as well.
+\end{key}
+
+\begin{key}{/pgfplots/table/white space chars=\marg{comma-separated-list} (initially empty)}
+ Allows to define a list of single characters which are actually treated like white spaces (in addition to tabs and spaces). Please refer to the manual of \PGFPlotstable\ for details.
+
+ This setting applies to |\addplot file| as well.
+\end{key}
+
+
\subsubsection{Computing Coordinates with Mathematical Expressions}
\begin{addplotoperation}[]{\marg{math expression}}{}
@@ -535,7 +607,7 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
\item If the $x$ axis is logarithmic, samples will be drawn logarithmically.
- \item Please note that plot expression does not allow per point meta data (color data).
+ \item Please note that plot expression does not allow separate per point meta data (color data). You can, of course, use |point meta=f(x)| or |point meta=x|.
\end{enumerate}
\paragraph{About the precision and number range:}
@@ -715,7 +787,7 @@ Since system calls are a potential danger, they need to be enabled explicitly us
\begin{codeexample}[code only]
pdflatex -shell-escape filename.tex.
\end{codeexample}
-Sometimes it is called |shell-escape| or |enable-write18|. Sometimes one needs two slashes -- that all depends on your \TeX\ distribution.
+Sometimes it is called |shell-escape| or |enable-write18|. Sometimes one needs two hyphens -- that all depends on your \TeX\ distribution.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
@@ -743,7 +815,7 @@ Some remarks:
For |parametric| plots, the variable names need to be adjusted with |parametric/var 1d| and |parametric/var 2d| (since gnuplot uses |t| and |u,v| as initial values for |parametric| plots).
\item
-Please note that |plot gnuplot| does not allow per point meta data (color data for each coordinate).
+Please note that |plot gnuplot| does not allow separate per point meta data (color data for each coordinate). You can, however, use |point meta=f(x)| or |point meta=x|.
\item The generated output file name can be customized with |id|, see below.
\end{itemize}
@@ -943,6 +1015,25 @@ Using |gv|, I determined that the bounding box needs to be shifted |12| units to
The \meta{options} are any arguments provided to the |includegraphics| key (see below) and |width| and |height| determined such that the graphics fits exactly into the rectangle denoted by the |xmin|, |ymin| and |xmax|, |ymax| coordinates.
The scaling will thus ignore the aspect ratio of the external image and prefer the one used by \PGFPlots. You will need to provide |width| and |height| to the \PGFPlots\ axis to change its scaling. Use the |scale only axis| key in such a case.
+
+\paragraph{Legends in \texttt{plot graphics}:} A legend for |plot graphics| uses the current plot handler and the current plot |mark|:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[axis on top,title=Graphics Import]
+ % provide options for the legend:
+ \addplot[red,only marks,mark=*,mark size=1pt]
+ graphics
+ [xmin=0,xmax=1,ymin=0,ymax=1,
+ % trim=left bottom right top
+ includegraphics={trim=12 9 12 8,clip}]
+ {external2};
+
+ \addplot coordinates {(0,0) (1,1)};
+
+ \legend{Scatter,Line}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
\end{addplotoperation}
\subsubsection*{Keys To Configure Plot Graphics}
@@ -957,6 +1048,9 @@ The following list of keys configure |\addplot graphics|. Note that the common p
\begin{pgfplotskey}{plot graphics/includegraphics=\marg{options}}
A list of options which will be passed as--is to |\includegraphics|. Interesting options include the \declareandlabel{trim}|=|\meta{left} \meta{bottom} \meta{right} \meta{top} key which reduces the bounding box and \pgfmanualpdflabel{/pgfplots/plot graphics/clip}{\declaretext{clip}} which discards everything outside of the bounding box. The scaling options won't have any effect, they will be overwritten by \PGFPlots.
\end{pgfplotskey}
+\begin{pgfplotskey}{plot graphics/includegraphics cmd=\marg{\textbackslash macro} (initially \textbackslash includegraphics)}
+ Allows to use a different graphics routine. A possible choice could be |\pgfimage|. The macro should accept the |width| and |height| arguments (in brackets) and the file name as first argument.
+\end{pgfplotskey}
\begin{stylekey}{/pgfplots/plot graphics/node}
A predefined style used for the \Tikz\ node containing the graphics. The predefined value is
\begin{codeexample}[code only]