summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-10-26 21:36:14 +0000
committerKarl Berry <karl@freefriends.org>2012-10-26 21:36:14 +0000
commit4147899f17a6e0b0dde20f309845c4fc0032bce9 (patch)
tree3609a0dc99736d7a2081187b9e12e9bac63c6bb6 /Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
parent3d12d871ae8a0e941fb2521bdc99ce436aeb17c6 (diff)
pgfplots (26oct12)
git-svn-id: svn://tug.org/texlive/trunk@28094 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex47
1 files changed, 39 insertions, 8 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
index 42a058d40a7..7830fd342ff 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplotstable.tex
@@ -1424,39 +1424,64 @@ The parameters can be customized using the optional integer argument(s): if $\te
\end{keylist}
-\begin{keylist}{/pgf/number format/relative=\meta{exponent base 10}}
+\begin{keylist}{/pgf/number format/relative*=\meta{exponent base 10}}
Configures |\pgfmathprintnumber| to format numbers relative to an order of magnitude, $10^r$, where $r$ is an integer number.
- The motivation is to provide a unified format for a \emph{sequence} of numbers:
+ This key addresses different use-cases.
+
+ \paragraph{First use-case:} provide a unified format for a \emph{sequence} of numbers. Consider the following test:
\begin{codeexample}[]
-\pgfkeys{/pgf/number format/relative={1}}
+\pgfkeys{/pgf/number format/relative*={1}}
\pgfmathprintnumber{6.42e-16}\hspace{1em}
\pgfmathprintnumber{1.2}\hspace{1em}
\pgfmathprintnumber{6}\hspace{1em}
\pgfmathprintnumber{20.6}\hspace{1em}
\pgfmathprintnumber{87}
\end{codeexample}
- \noindent With any other style, the |6.42e-16| would have been formatted as an isolated number. Here, it is rounded to |0| because when viewed relative to $10^3$, it has no significant digits.
+ \noindent With any other style, the |6.42e-16| would have been formatted as an isolated number. Here, it is rounded to |0| because when viewed relative to $10^1$ (the exponent $1$ is the argument for |relative|), it has no significant digits.
\begin{codeexample}[]
-\pgfkeys{/pgf/number format/relative={2}}
+\pgfkeys{/pgf/number format/relative*={2}}
\pgfmathprintnumber{123.345}\hspace{1em}
\pgfmathprintnumber{0.0012}\hspace{1em}
\pgfmathprintnumber{0.0014}\hspace{1em}
\end{codeexample}
- Here, it applies the initial |precision=2| to |123.345| -- relative to $100$. Two significant digits of |123.345| relative to $100$ are |123|. Similarly, the other two numbers are |0| compared to $100$ using the given |precision|.
+ \noindent The example above applies the initial |precision=2| to |123.345| -- relative to $100$. Two significant digits of |123.345| relative to $100$ are |123|. Note that the ``$2$ significant digits of |123.345|'' translates to ``round |1.2345| to $2$ digits'', which would yield |1.2300|. Similarly, the other two numbers are |0| compared to $100$ using the given |precision|.
\begin{codeexample}[]
-\pgfkeys{/pgf/number format/relative={-3}}
+\pgfkeys{/pgf/number format/relative*={-3}}
\pgfmathprintnumber{123.345}\hspace{1em}
\pgfmathprintnumber{0.0012}\hspace{1em}
\pgfmathprintnumber{0.0014}\hspace{1em}
\end{codeexample}
+ \paragraph{Second use-case:} improve rounding in the presence of \emph{inaccurate} numbers. Let us suppose that some limited-precision arithmetics resulted in the result |123456999| (like the |fpu| of \pgfname). You know that its precision is about five or six significant digits. And you want to provide a fixed point output. In this case, the trailing digits |....999| are a numerical artifact due to the limited precision. Use |relative*=3,precision=0| to eliminate the artifacts:
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0}
+\pgfmathprintnumber{123456999}\hspace{1em}
+\pgfmathprintnumber{123456999.12}
+\end{codeexample}
+\noindent Here, |precision=0| means that we inspect |123456.999| and round that number to $0$ digits. Finally, we move the period back to its initial position. Adding |relative style=fixed| results in fixed point output format:
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0,relative style=fixed}
+\pgfmathprintnumber{123456999}\hspace{1em}
+\pgfmathprintnumber{123456999.12}
+\end{codeexample}
+ \noindent Note that there is another alternative for this use-case which is discussed later: the |fixed relative| style.
+\begin{codeexample}[]
+\pgfkeys{/pgf/number format/.cd,fixed relative,precision=6}
+\pgfmathprintnumber{123456999}\hspace{1em}
+\pgfmathprintnumber{123456999.12}
+\end{codeexample}
+
+ You might wonder why there is an asterisk in the key's name. The short answer is: there is also a \declareandlabel{/pgf/number format/relative} number printer which does unexpected things. The key |relative*| repairs this. Existing code will still use the old behavior.
- When applied to a number $x = \pm m \cdot 10^e$, the |relative=|$r$ method actually rounds $x / 10^r$ to the desired precision. More precisely: if $e-r>0$, it only rounds the mantissa of $x/10^r$ to the desired precision, otherwise it rounds the complete number to the desired precision. Afterwards, it disables rounding, multiplies the intermediate result by $10^r$, and evaluates the style |every relative| to actually format the result.
+
+ Technically, the key works as follows: as already explained above, |relative*=3| key applied to |123456999.12| moves the period by three positions and analyzes |123456.99912|. Mathematically speaking, we are given a number $x = \pm m \cdot 10^e$ and we attempt to apply |relative*=|$r$. The method then rounds $x / 10^r$ to |precision| digits. Afterwards, it multiplies the result by $10^r$ and typesets it.
+
\end{keylist}
+
\begin{stylekey}{/pgf/number format/every relative}
A style which configures how the |relative| method finally displays its results.
@@ -1470,6 +1495,10 @@ The parameters can be customized using the optional integer argument(s): if $\te
Although supported, I discourage from using |fixed zerofill| or |sci zerofill| in this context -- it may lead to a suggestion of higher precision than is actually used (because |fixed zerofill| might simply add |.00| although there was a different information before |relative| rounded the result).
\end{stylekey}
+\begin{key}{/pgf/number format/relative style=\marg{options}}
+ The same as |every relative/.append style=|\marg{options}.
+\end{key}
+
\begin{keylist}{/pgf/number format/fixed relative}
Configures |\pgfmathprintnumber| to format numbers in a similar way to the |fixed| style, but the |precision| is interpreted relatively to the number's exponent.
@@ -1490,6 +1519,8 @@ The parameters can be customized using the optional integer argument(s): if $\te
Use |fixed relative| if you want |fixed| and if you know that only the first $n$ digits are correct. Use |sci| if you need a scientific display style and only the first $n$ digits are correct.
Note that |fixed relative| ignores the |fixed zerofill| flag.
+
+ See also the |relative*| key. Note that the |relative=|\marg{exponent} key explicitly moves the period to some designated position before it attempts to round the number. Afterwards, it ``rounds from the right'', i.e.\ it rounds to that explicitly chosen digit position. In contrast to that, |fixed relative| ``rounds from the left'': it takes the \emph{first} non-zero digit, temporarily places the period after this digit, and rounds that number. The rounding style |fixed| leaves the period where it is, and rounds everything behind that digit. The |sci| style is similar to |fixed relative|.
\end{keylist}
\begin{key}{/pgf/number format/int detect}