summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex45
1 files changed, 40 insertions, 5 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
index baceab56f8e..4aa02209c7a 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.coordfiltering.tex
@@ -1,11 +1,12 @@
\subsection{Skipping Or Changing Coordinates -- Filters}
+\label{sec: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 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| (on input, the same value is stored in |\pgfmathresult|), 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.
+The |filter point/.code| filter allows filtering depending 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.
+It is allowed that 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.
@@ -51,8 +52,9 @@ There is also a style key which simplifies selection by index, see below.
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.
+ 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{new value}; access to variables can be accessed 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.
+ Note that you can provide different |x filter|/|y filter| arguments to each |\addplot| command. It seems there are only problems with the `|#1|' argument, and I haven't yet found out why. Please use |\pgfmathresult| in place of |#1| if you provide |\addplot[x filter/.code={...}]|.
\end{pgfplotsxycodekeylist}
\begin{stylekey}{/pgfplots/skip coords between index=\marg{begin}\marg{end}}
@@ -68,11 +70,27 @@ There is also a style key which simplifies selection by index, see below.
\end{axis}
\end{tikzpicture}
\end{codeexample}
+
+ \paragraph{Technical note}: this style usually applies to $x$ coordinates (i.e.\ it counts $x$ coordinates). In case you want to apply it to something like |hist/data| or |quiver/u|, you can
+ \begin{enumerate}
+ \item append an asterisk `|*|' to the style's name and
+ \item provide the target coordinate's name as first argument.
+ \end{enumerate}
+ For example, |skip coords between index*={hist/data}{2}| applies to |hist/data|.
\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}
+
+ Note that there is also a |mark repeat| style which applies the same operation to plot marks only.
+
+ \paragraph{Technical note}: this style usually applies to $x$ coordinates (i.e.\ it counts $x$ coordinates). In case you want to apply it to something like |hist/data| or |quiver/u|, you can
+ \begin{enumerate}
+ \item append an asterisk `|*|' to the style's name and
+ \item provide the target coordinate's name as first argument.
+ \end{enumerate}
+ For example, |each nth point*={hist/data}{2}| applies to |hist/data|.
\end{pgfplotskey}
\begin{pgfplotsxykeylist}{
@@ -91,7 +109,7 @@ There is also a style key which simplifies selection by index, see below.
\begin{axis}[
restrict y to domain=-10:10,
samples=1000,
- % some fine tuning for the display:
+ % some fine-tuning for the display:
width=10cm, height=210pt,
xmin=-4.7124, xmax=4.7124,
xtick={-4.7124,-1.5708,...,10},
@@ -119,7 +137,24 @@ There is also a style key which simplifies selection by index, see below.
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{pgfplotskeylist}
+\begin{pgfplotskey}{@restrict to domain=\marg{filter name}\marg{expression}\marg{\meta{min}:\meta{max}}\mchoice{0,1}}
+ A low--level (technical) key which allows to apply the |restrict * to ...| features also to something like |hist/data|.
+
+ For example,
+ |@restrict to domain={hist/data}{}{0:1}{0}| applies the domain-restriction to the histogram-input |hist/data|. The final `|0|' means that it works as the key |restrict x to domain=0:1|, i.e.\ it skips everything which is outside of $[0,1]$. In a similar way,
+ |@restrict to domain={hist/data}{}{0:1}{1}| applies the functionality of |restrict x to domain*=0:1| to |hist/data|: it truncates values outside of $[0,1]$ to the domain's end-points.
+
+ The \meta{filter name} is expected to be a coordinate name like |x|, |y|, |z| (or |hist/data|).
+
+ The \meta{expression} configures an expression which will be used rather than the value of \meta{filter name}. It can be empty.
+
+ The \meta{min}\texttt{:}\meta{max} are as described above.
+
+ If the last argument is |1|, any coordinate outside of the allowed domain will take the domain boundary as value. If it is |0|, such a coordinate will get either |inf| or |-inf|.
+\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}
+You can find somewhat more on coordinate filtering in Section~\ref{pgfplots:interrupt}: ``Interrupted Plots''.