pgfplots 1.6.1 (29aug12)

git-svn-id: svn://tug.org/texlive/trunk@27550 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 235 insertions, 60 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 2cbbc623b96..b4a4a6f5296 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
@@ -222,12 +222,56 @@ Thus, you can combine |cycle list| and \meta{options}.
 The distinction is as follows: |\addplot  ...| (without options) lets \PGFPlots\ select colors, markers and linestyles automatically (using |cycle list|). The variant |\addplot+|\oarg{option}| ...| will use the same automatically determined styles, but in addition it uses \meta{options}. Finally, |\addplot|\oarg{options} (without the |+|) uses only the manually provided \meta{options}.
 \end{addplot+}
 
+\begin{pgfplotskey}{empty line=\mchoice{auto,none,scanline,jump} (initially auto)}
+	Controls how empty lines in the input coordinate stream are to be interpreted. You should ensure that you have |\pgfplotsset{compat=1.4}| or newer in your preamble and leave this key at its default |empty line=auto|.
+
+	Empty lines can occur between the coordinates of |\addplot coordinates| or successive rows of the data file input routines |\addplot table| (and |\addplot file|).
+
+	The choice \declaretext{auto} checks if the current plot type is |mesh| or |surf|. If so, it uses |scanline|. If the current plot type is some other plot type (like a standard line plot), it uses |jump|. Note that the value \texttt{auto} for non-mesh plots results in \texttt{none} if |compat=1.3| or older is used. In other words: you have to write |\pgfplotsset{compat=1.4}| or newer to let \PGFPlots\ interpret empty lines as |jump| in standard line plots:
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{axis}[tiny,
+		title={Ignored: compat=1.3},
+		compat=1.3]
+	\addplot table {
+	A B
+	0 0
+	1 1
+
+	1 2
+	2 2
+	};
+	\end{axis}
+\end{tikzpicture}
+\begin{tikzpicture}
+	\begin{axis}[tiny,
+		title={Jump: compat=1.4},
+		compat=1.4]
+	\addplot table {
+	A B
+	0 0
+	1 1
+
+	1 2
+	2 2
+	};
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+	The choice \declaretext{scanline} is only useful for |mesh| and |surf|: it is used to decode a matrix from a coordinate stream. If an empty line occurs once every $N$ data points, the ``scanline'' length is~$N$. This information, together with |mesh/ordering| and the total number of points, allows to deduce the matrix size. However, the distance between empty lines has to be consistent: if the first two empty lines have a distance of~$2$ and the next comes after~$5$, \PGFPlots\ will ignore the information and will expect explicit matrix sizes using |mesh/rows| and/or |mesh/cols|. The choice |scanline| is ignored if |mesh input=patches|. It has no effect for other plot types.
+
+	The choice \declaretext{none} will silently discard any empty line in the input stream.
+
+	The choice \declaretext{jump} tells \PGFPlots\ to generate a jump.
+\end{pgfplotskey}
+
 \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.
+The `|\addplot 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}
@@ -239,7 +283,10 @@ The `|plot coordinates|' command is like that provided by \Tikz\ and reads its i
 \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 should \empty{only} use this input format if you have short diagrams and you want to provide mathematical expressions for each of the involved coordinates. Any data plots are typically easier to handle using a table format and |\addplot table|.
+
+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}[]
@@ -280,6 +327,8 @@ Furthermore, |coordinates| allows to define ``meta data'' for each coordinate. T
 \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.
+
+	The coordinate stream can contain |empty line|s to tell \PGFPlots\ that the function has jumps. To use it, simply insert an empty line (and ensure that you have |\pgfplotsset{compat=1.4}| or newer in your preamble). See the documentation of |empty line| for details.
 \end{addplotoperation}
 
 \begin{pgfplotskey}{plot coordinates/math parser=\mchoice{true,false} (initially true)}
@@ -288,61 +337,14 @@ Please refer to the documentation of |point meta| on page~\pageref{pgfplots:poin
 	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 \meta{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}}
+\begin{addplotoperation}[]{table}{\oarg{column selection}\marg{file or inline table}}
 \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
+This input method is the main input format for any data--based function. It accepts either a file containing data or an inline table provided in curly braces.
+
+Given a data file like
 \begin{codeexample}[code only]
 dof     L2              Lmax            maxlevel
 5       8.31160034e-02  1.80007647e-01  2
@@ -470,8 +472,12 @@ Summary and remarks:
 
 	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.
 
+	\item
+	The table can contain |empty line|s to tell \PGFPlots\ that the function has jumps. To use it, simply insert an empty line (and ensure that you have |\pgfplotsset{compat=1.4}| or newer in your preamble). See the documentation of |empty line| for details.
 	\item Technical note: every opened file will be protocolled into your log file.
+
 \end{itemize}
+
 \end{addplotoperation}
 
 \subsubsection*{Keys To Configure Table Input}
@@ -1140,9 +1146,9 @@ The following list of keys configure |\addplot graphics|. Note that the common p
 
 The |plot graphics| tool of \PGFPlots\ allows to include three--dimensional external graphics: it generates a three--dimensional axis on its own. The idea is to provide a graphics (without descriptions) and use \PGFPlots\ to overlay a three--dimensional axis automatically. This allows to maintain document consistency (making it unnecessary to use different programs within the same document). 
 
-You are probably guessing how this is possible. Well, it needs more user input than two--dimensional external graphics. The cost to include external three dimensional images into \PGFPlots\ is essentially control of a graphics program like |gimp|: you need to identify the 3D coordinates of a couple of points in your image. \PGFPlots\ will then squeeze the graphics correctly, and it reconfigures the axis to ensure a correct display of the result.
+You are probably wondering how this is possible. Well, it needs more user input than two--dimensional external graphics. The cost to include external three dimensional images into \PGFPlots\ is essentially control of a graphics program like |gimp|: you need to identify the 3D coordinates of a couple of points in your image. \PGFPlots\ will then squeeze the graphics correctly, and it reconfigures the axis to ensure a correct display of the result.
 
-\paragraph{Warning:} The feature is only 95\% stable yet and may need some more testing. Use at your own risk.
+\paragraph{Matlab versus other tools:} Although this section is based on Matlab images, the technique to import three--dimensional graphics is independent of Matlab. Thus, if you have a different tool, you need to read all that follows. However, users of Matlab \emph{can use a simplified export mechanism} which has been contributed by J\"urnjakob Dugge. Please skip to section~\ref{sec:plotgraphics3d:matlabscript} on page~\pageref{sec:plotgraphics3d:matlabscript} if you use Matlab to generate the graphics files (although you may want to take a brief look at the examples on the following pages to learn about flexibility or legends).
 
 Let's start with two examples. Suppose you generate a surface plot with Matlab and want to include it in \PGFPlots. We have the matlab script
 \begin{codeexample}[code only]
@@ -1228,7 +1234,7 @@ Once these four point coordinates are gathered, we find Matlab's surface plot in
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
-\noindent \PGFPlots\ uses the four input points to compute appropriate |x|, |y| and |z| unit vectors (and the origin in graphics coordinates). These four vectors (with two components each) can be computed as a result of a linear system of size $8\times 8$, that is why you need to provide four input points (each has two coordinates). \PGFPlots\ computes the unit vectors of the imported graphics, and afterwards it rescales the result such that it fits into the specified |width| and |height|. This rescaling respects the |unit vector ratio| (more precisely, it uses |scale mode=scale uniformly| instead of |scale mode=stretch to fill|). Consequently, the freedom to change the view of a three--dimensional axis which contains a projected graphics is considerably smaller than before. Surprisingly, you can still change axis limits and |width| and |height| -- \PGFPlots\ will take care of a correct display of your imported graphics.
+\noindent \PGFPlots\ uses the four input points to compute appropriate |x|, |y| and |z| unit vectors (and the origin in graphics coordinates). These four vectors (with two components each) can be computed as a result of a linear system of size $8\times 8$, that is why you need to provide four input points (each has two coordinates). \PGFPlots\ computes the unit vectors of the imported graphics, and afterwards it rescales the result such that it fits into the specified |width| and |height|. This rescaling respects the |unit vector ratio| (more precisely, it uses |scale mode=scale uniformly| instead of |scale mode=stretch to fill|). Consequently, the freedom to change the view of a three--dimensional axis which contains a projected graphics is considerably smaller than before. Surprisingly, you can still change axis limits and |width| and |height| -- \PGFPlots\ will take care of a correct display of your imported graphics. Since version~1.6, you can also change |zmin| and/or |zmax| -- \PGFPlots\ will respect your changes as good as it can.
 
 Here is a further example. Suppose we are given the three--dimensional visualization
 
@@ -1265,7 +1271,7 @@ It has been generated by matlab (I only added transparency to the background wit
 \end{codeexample}
 \noindent Note that I provided \emph{five} three--dimensional coordinates here, but the last entry has no |=>| mapping to two--dimensional canvas coordinates. Thus, it is only used to update the bounding box (see the reference manual for the |points| key for details).
 
-The example above is clipped because \PGFPlots\ could not rescale the graphics automatically. Changing the ratio between |width| and |height| improves the display:
+The example above leads to a relatively small image and much ``empty space''. This is due to the |scale mode=scale uniformly| implementation of \PGFPlots: it decided that the best way is to enlarge the involved axis limits. Here, ``best way'' means to satisfy |width|/|height| constraints combined with minimally enlarged (never shrinked) axis limits. The remaining degrees of freedom are |width|, |height|, and the axis limits. In our case, changing the ratio between |width| and |height| improves the display:
 
 \begin{codeexample}[]
 \begin{tikzpicture}
@@ -1291,7 +1297,11 @@ The example above is clipped because \PGFPlots\ could not rescale the graphics a
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
-\noindent What happens is that \PGFPlots\ \emph{only} rescales the $z$ axis. This has the effect that the axes are all scaled by a single scaling factor (using |scale mode=scale uniformly|), skewing is avoided. In this approach, you can only modify |width| and |height| to provide more freedom.
+\noindent What happens is that \PGFPlots\ selects a \emph{single} scaling factor which is applied to all units as they have been deduced from the |points| key. This ensures that the imported graphics fits correctly into the axis. In addition, \PGFPlots\ does its best to satisfy the remaining constraints. 
+
+The complete description of how \PGFPlots\ scales the axis can be found in the documentation for |scale mode=scale uniformly|. Here is just a brief summary: \PGFPlots\ assumes that the prescribed |width| and |height| have to be satisfied. To this end, it rescales the projected unit vectors (i.e.\ the space which is taken up for each unit in $x$, $y$, and $z$) and it can modify the axis limits. In the default configuration |scale uniformly strategy=auto|, \PGFPlots\ will \emph{never} shrink axis limits.  
+
+\paragraph{Compatibility remark:} Note that the scaling capabilities have been improved for \PGFPlots\ version~1.6. In previous versions, only |scale uniformly strategy=change vertical limits| was available which lead to clipped axes. In short: please consider writing |\pgfplotsset{compat=1.6}| or newer into your document to benefit from the improved scaling. If you have |\pgfplotsset{compat=1.5}| or older, the outcome for |\addplot3 graphics| will be different.
 
 We consider a third example which has been generated by the Matlab code
 \begin{codeexample}[code only]
@@ -1342,15 +1352,126 @@ We proceed as before and collect four points, each with 3d logical coordinates (
 \end{axis}
 \end{tikzpicture}
 \end{codeexample}
+\noindent Note that it has non-standard data aspect ratio which is respected by \PGFPlots\ automatically.
+
+
+\subsubsection*{External Three-Dimensional Graphics and Matlab}
+
+\textit{An extension by J\"urnjakob Dugge}
+\vskip\baselineskip
+
+\noindent
+\label{sec:plotgraphics3d:matlabscript}
+The procedure to map three--dimensional logical coordinates to two--dimensional canvas coordinates is tedious.
+
+J\"urnjakob Dugge contributed a script which does most of the logic and your work is reduced to a copy--paste job. With his permission, I post the contribution here. 
+
+The idea is to start a simple script which \emph{records} mappings for any coordinates which have been clicked by the user. It works as follows:
+
+\begin{enumerate}
+	\item Create the Matlab plot, say, using
+\begin{codeexample}[code only]
+hist3(randn(10000,2)) % some random data
+set(get(gca,'child'),'FaceColor','interp','CDataMode','auto'); % colors
+% make sure the "print" paper format is the same as the screen paper format:
+set(gcf,'PaperPositionMode','auto') 
+\end{codeexample}
+
+	\item Save the following code as |pgfplotscsconversion.m|:
+\begin{codeexample}[code only]
+function pgfplotscsconversion
+
+% Hook into the Data Cursor "click" event
+h = datacursormode(gcf);
+set(h,'UpdateFcn',@myupdatefcn,'SnapToDataVertex','off');
+datacursormode on
 
-\paragraph{Technical points:} the following issues might arise while working with \verbpdfref{\addplot3} |graphics|:
+% select four points in plot using mouse
+
+% The function that gets called on each Data Cursor click
+function [txt] = myupdatefcn(obj,event_obj)
+
+% Get the screen resolution, in dots per inch
+dpi = get(0,'ScreenPixelsPerInch');
+
+% Get the click position in pixels, relative to the lower left of the
+% screen
+screen_location=get(0,'PointerLocation');
+
+% Get the position of the plot window, relative to the lower left of
+% the screen
+figurePos = get(gcf,'Position');
+
+% Get the data coordinates of the cursor
+pos = get(event_obj,'Position');
+
+% Format the data and figure coordinates. The factor "72.27/dpi" is
+% necessary to convert from pixels to TeX points (72.27 poins per inch)
+display(['(',num2str(pos(1)),',',num2str(pos(2)),',',num2str(pos(3)),') => (', ...
+   num2str((screen_location(1)-figurePos(1))*72.27/dpi),',', ...
+   num2str((screen_location(2)-figurePos(2))*72.27/dpi),')'])
+
+% Format the tooltip display
+txt = {['X: ',num2str(pos(1))],['Y: ',num2str(pos(2))],['Z: ',num2str(pos(3))]};
+\end{codeexample}
+	
+	Run |pgfplotscsconversion|, click on four points in your plot. Preferably select non-colinear points near the edges of the plot. Copy and paste the four lines that were written to the Matlab command window.
+
+	Make sure that the first two points have different $X$ and $Y$ values on screen (i.e.\ image canvas coordinates).
+	\item Export the plot as an image
+\begin{codeexample}[code only]
+axis off
+print -dpng matlabout -r400 % PNG called "matlabout.png" with 400 dpi resolution
+\end{codeexample}
+
+Note that |pdf| output of Matlab is clumsy. It might be best to export to |eps| first, followed by a conversion from |eps| to |pdf|.
+
+\emph{If} you really want to use |pdf| output of Matlab, you may need to set the paper size to match the figure size by yourself, since the PDF driver does not automatically adjust the size:
+
+\begin{codeexample}[code only]
+% It might be better to use print -depsc  followed by epstopdf. 
+% Use this if you (really) want to use print -dpdf:
+currentScreenUnits=get(gcf,'Units')     % Get current screen units
+currentPaperUnits=get(gcf,'PaperUnits') % Get current paper units
+set(gcf,'Units',currentPaperUnits)      % Set screen units to paper units
+plotPosition=get(gcf,'Position')        % Get the figure position and size
+set(gcf,'PaperSize',plotPosition(3:4))  % Set the paper size to the figure size
+set(gcf,'Units',currentScreenUnits)     % Restore the screen units
+
+print -dpdf matlabout      % PDF called "matlabout.pdf"
+\end{codeexample}
+\item Include the image in your \PGFPlots\ axis. If you selected points on the plot corners, your |xmin|, |xmax|, |ymin| and |ymax| should be set automatically, otherwise you may want to provide those yourself. Also, adjustments of |width| and |height| might be of interest to get the right vertical placement of the plot. Consider changing |zmin| and/or |zmax| to fit your needs (preferrably only one of them; otherwise \PGFPlots\ may be unable to fix the |height|).
+\end{enumerate}
+
+This contribution is from
+
+\noindent
+\url{http://tex.stackexchange.com/questions/52987/3-dimensional-histogram-in-pgfplots} .
+
+
+
+\subsubsection*{Summary: External Three-Dimensional Graphics}
+As has been shown in the previous sections, \verbpdfref{\addplot3} |graphics| allows to include three-dimensional graphics and \PGFPlots\ overlays a flexible axis with all its power. The cost to do so is
+\begin{enumerate}
+	\item collect both logical three--dimensional coordinates \emph{and} image--internal two--dimensional coordinates for \emph{four points} of your graphics.
+
+	In Matlab, this can be simplified by the tool mentioned on page~\pageref{sec:plotgraphics3d:matlabscript}.
+
+	\item If your axes form a right--handed--coordinate system, that is all. If not, also add |x dir=reverse| for any reversed axes.
+\end{enumerate}
+
+\noindent
+Consider the following list of you encounter problems while working with \verbpdfref{\addplot3} |graphics|:
 \begin{itemize}
 	\item It must be possible to deduce the origin and the three (two--dimensional) unit vectors from the four provide |points|; otherwise the algorithm will fail. 
 	
 	The algorithm should detect any deficiancies. However, if you encounter strange ``Dimension too large'' messages here, you can try other arguments in |points|. Take a look into your log file, it will probably indicate the source of problems (or use the |debug| key).
 
 	\item \PGFPlots\ uses the first two points to squeeze the graphics into the desired coordinates (which implies that they should not have the same canvas $X$ or $Y$ coordinates). It verifies that the remaining |points| arguments are projected correctly.
-	\item The resulting scaling by means of |scale mode=scale uniformly| will only rescale the $z$ axis. You may need to adjust |width| and |height| (both of them) if the result is unsatisfactory (see the example above).
+	\item The resulting scaling by means of |scale mode=scale uniformly| will try to satisfy all scaling constraints. You can change these constraints by modifying |width|, |height|, |xmin|, |xmax|, |ymin|, |ymax|, |zmin|, |zmax| and/or any combination of these parameters. See also |unit rescale keep size| which controls the flexibility of limit changes. There is also a key |scale uniformly strategy| which allows to select a different scaling strategy.
+	 
+	\item The image should have a ``right--handed--coordinate system'': you should be able to take your right hand, point your thumb in direction of the $x$ axis, your first finger in direction of~$y$, and your second finger in direction of the $z$~axis. If that is impossible, once of your axes is reversed and you need to communicate that to \PGFPlots\ explicitly by means of the |x dir=reverse| key (and its variants).
+
 	\item There is a |debug| key to investigate what the algorithm is doing:
 \begin{pgfplotskey}{plot graphics/debug=\marg{true,false} (initially false)}
 	If you provide |\addplot3 graphics[debug,points={...}]|, \PGFPlots\ will provide debug information onto your terminal and into the logfile. It will also generate extra files containing the determined unit vectors and the linear system used to derive them (one such file for every |\addplot3 graphics| statement, the filename will be the graphics file name and |.dat| appended).
@@ -1360,4 +1481,58 @@ We proceed as before and collect four points, each with 3d logical coordinates (
 \end{itemize}
 }
 
+\subsubsection{Reading Coordinates From Files}
+
+\begin{addplotoperation}[]{file}{\marg{name}}
+\label{pgfplots:addplot:file}
+\paragraph{Deprecation note:} If you have data files, you should generally use |\addplot table|. The input type |\addplot file| is almost the same, but considerably less powerful. It is only kept for backwards compatibility.
+
+
+The |\addplot file| input mechanism 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 \meta{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.
+
+	The file can contain |empty line|s to tell \PGFPlots\ that the function has jumps. To use it, simply insert an empty line (and ensure that you have |\pgfplotsset{compat=1.4}| or newer in your preamble). See the documentation of |empty line| for details.
+\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}
 }%