![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdgraph_rpn.1 b/doc/rrdgraph_rpn.1
index 4cfdcbb3ce68d967a288e290ee3956a6886d5edd..2a34298e8aeb50fa8cfaf908b925da910c3d203e 100644 (file)
--- a/doc/rrdgraph_rpn.1
+++ b/doc/rrdgraph_rpn.1
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
. ds R" ''
'br\}
.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+. de IX
+..
+.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "RRDGRAPH_RPN 1"
-.TH RRDGRAPH_RPN 1 "2009-02-21" "1.3.7" "rrdtool"
+.TH RRDGRAPH_RPN 1 "2012-01-18" "1.4.7" "rrdtool"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
.SH "NAME"
rrdgraph_rpn \- About RPN Math in rrdtool graph
.SH "SYNOPSIS"
.Sp
Pop two elements from the stack, compare them for the selected condition
and return 1 for true or 0 for false. Comparing an \fIunknown\fR or an
-\&\fIinfinite\fR value will always result in 0 (false).
+\&\fIinfinite\fR value will result in \fIunknown\fR returned ... which will also be
+treated as false by the \fB\s-1IF\s0\fR call.
.Sp
\&\fB\s-1UN\s0, \s-1ISINF\s0\fR
.Sp
.Sp
Example: \f(CW\*(C`A,B,C,IF\*(C'\fR should be read as \f(CW\*(C`if (A) then (B) else (C)\*(C'\fR
.Sp
-\&\&
+
.IP "Comparing values" 4
.IX Item "Comparing values"
\&\fB\s-1MIN\s0, \s-1MAX\s0\fR
Example: \f(CW\*(C`CDEF:a=alpha,0,100,LIMIT\*(C'\fR will return \fIunknown\fR if
alpha is lower than 0 or if it is higher than 100.
.Sp
-\&\&
+
.IP "Arithmetics" 4
.IX Item "Arithmetics"
\&\fB+, \-, *, /, %\fR
\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
\& delay t2
\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
-.Ve
-.Sp
-.Vb 3
+\&
+\&
\& Value at sample (t0) will be the average between (t0\-delay) and (t0)
\& Value at sample (t1) will be the average between (t1\-delay) and (t1)
\& Value at sample (t2) will be the average between (t2\-delay) and (t2)
.Ve
.Sp
-\&\s-1TRENDNAN\s0 is \- in contrast to \s-1TREND\s0 \- NAN\-safe. If you use \s-1TREND\s0 and one
+\&\s-1TRENDNAN\s0 is \- in contrast to \s-1TREND\s0 \- NAN-safe. If you use \s-1TREND\s0 and one
source value is \s-1NAN\s0 the complete sliding window is affected. The \s-1TRENDNAN\s0
operation ignores all NAN-values in a sliding window and computes the
average of the remaining values.
+.Sp
+\&\fB\s-1PREDICT\s0, \s-1PREDICTSIGMA\s0\fR
+.Sp
+Create a \*(L"sliding window\*(R" average/sigma of another data series, that also
+shifts the data series by given amounts of of time as well
+.Sp
+Usage \- explicit stating shifts:
+CDEF:predict=<shift n>,...,<shift 1>,n,<window>,x,PREDICT
+CDEF:sigma=<shift n>,...,<shift 1>,n,<window>,x,PREDICTSIGMA
+.Sp
+Usage \- shifts defined as a base shift and a number of time this is applied
+CDEF:predict=<shift multiplier>,\-n,<window>,x,PREDICT
+CDEF:sigma=<shift multiplier>,\-n,<window>,x,PREDICTSIGMA
+.Sp
+Example:
+CDEF:predict=172800,86400,2,1800,x,PREDICT
+.Sp
+This will create a half-hour (1800 second) sliding window average/sigma of x, that
+average is essentially computed as shown here:
+.Sp
+.Vb 10
+\& +\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\->
+\& now
+\& shift 1 t0
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& window
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& shift 2
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& window
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& shift 1 t1
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& window
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& shift 2
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& window
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\&
+\& Value at sample (t0) will be the average between (t0\-shift1\-window) and (t0\-shift1)
+\& and between (t0\-shift2\-window) and (t0\-shift2)
+\& Value at sample (t1) will be the average between (t1\-shift1\-window) and (t1\-shift1)
+\& and between (t1\-shift2\-window) and (t1\-shift2)
+.Ve
+.Sp
+The function is by design NAN-safe.
+This also allows for extrapolation into the future (say a few days)
+\&\- you may need to define the data series whit the optional start= parameter, so that
+the source data series has enough data to provide prediction also at the beginning of a graph...
+.Sp
+Here an example, that will create a 10 day graph that also shows the
+prediction 3 days into the future with its uncertainty value (as defined by avg+\-4*sigma)
+This also shows if the prediction is exceeded at a certain point.
+.Sp
+rrdtool graph image.png \-\-imgformat=PNG \e
+ \-\-start=\-7days \-\-end=+3days \-\-width=1000 \-\-height=200 \-\-alt\-autoscale\-max \e
+ DEF:value=value.rrd:value:AVERAGE:start=\-14days \e
+ LINE1:value#ff0000:value \e
+ CDEF:predict=86400,\-7,1800,value,PREDICT \e
+ CDEF:sigma=86400,\-7,1800,value,PREDICTSIGMA \e
+ CDEF:upper=predict,sigma,3,*,+ \e
+ CDEF:lower=predict,sigma,3,*,\- \e
+ LINE1:predict#00ff00:prediction \e
+ LINE1:upper#0000ff:upper\e certainty\e limit \e
+ LINE1:lower#0000ff:lower\e certainty\e limit \e
+ CDEF:exceeds=value,UN,0,value,lower,upper,LIMIT,UN,IF \e
+ TICK:exceeds#aa000080:1
+.Sp
+Note: Experience has shown that a factor between 3 and 5 to scale sigma is a good
+discriminator to detect abnormal behavior. This obviously depends also on the type
+of data and how \*(L"noisy\*(R" the data series is.
+.Sp
+This prediction can only be used for short term extrapolations \- say a few days into the future\-
.IP "Special values" 4
.IX Item "Special values"
\&\fB\s-1UNKN\s0\fR
.IP "Time" 4
.IX Item "Time"
Time inside RRDtool is measured in seconds since the epoch. The
-epoch is defined to be \f(CW\*(C`Thu\ Jan\ 1\ 00:00:00\ UTC\ 1970\*(C'\fR.
+epoch is defined to be \f(CW\*(C`Thu\ Jan\ \ 1\ 00:00:00\ UTC\ 1970\*(C'\fR.
.Sp
\&\fB\s-1NOW\s0\fR
.Sp
Duplicate the top element, remove the top element, exchange the two
top elements.
.Sp
-\&\&
+
.SH "VARIABLES"
.IX Header "VARIABLES"
These operators work only on \fB\s-1VDEF\s0\fR statements. Note that currently \s-1ONLY\s0 these work for \fB\s-1VDEF\s0\fR.
Example: \f(CW\*(C`VDEF:stdev=mydata,STDEV\*(C'\fR
.IP "\s-1LAST\s0, \s-1FIRST\s0" 4
.IX Item "LAST, FIRST"
-Return the last/first value including its time. The time for
-\&\s-1FIRST\s0 is actually the start of the corresponding interval, whereas
-\&\s-1LAST\s0 returns the end of the corresponding interval.
+Return the last/first non-nan or infinite value for the selected data
+stream, including its timestamp.
.Sp
Example: \f(CW\*(C`VDEF:first=mydata,FIRST\*(C'\fR
.IP "\s-1TOTAL\s0" 4
.IX Item "TOTAL"
Returns the rate from each defined time slot multiplied with the
-step size. This can, for instance, return total bytes transfered
+step size. This can, for instance, return total bytes transferred
when you have logged bytes per second. The time component returns
the number of seconds.
.Sp
Example: \f(CW\*(C`VDEF:total=mydata,TOTAL\*(C'\fR
-.IP "\s-1PERCENT\s0" 4
-.IX Item "PERCENT"
+.IP "\s-1PERCENT\s0, \s-1PERCENTNAN\s0" 4
+.IX Item "PERCENT, PERCENTNAN"
This should follow a \fB\s-1DEF\s0\fR or \fB\s-1CDEF\s0\fR \fIvname\fR. The \fIvname\fR is popped,
another number is popped which is a certain percentage (0..100). The
data set is then sorted and the value returned is chosen such that
\&\fIpercentage\fR percent of the values is lower or equal than the result.
+For \s-1PERCENTNAN\s0 \fIUnknown\fR values are ignored, but for \s-1PERCENT\s0
\&\fIUnknown\fR values are considered lower than any finite number for this
purpose so if this operator returns an \fIunknown\fR you have quite a lot
of them in your data. \fBInf\fRinite numbers are lesser, or more, than the
(NaN < \-INF < finite values < \s-1INF\s0)
.Sp
Example: \f(CW\*(C`VDEF:perc95=mydata,95,PERCENT\*(C'\fR
+ \f(CW\*(C`VDEF:percnan95=mydata,95,PERCENTNAN\*(C'\fR
.IP "\s-1LSLSLOPE\s0, \s-1LSLINT\s0, \s-1LSLCORREL\s0" 4
.IX Item "LSLSLOPE, LSLINT, LSLCORREL"
Return the parameters for a \fBL\fReast \fBS\fRquares \fBL\fRine \fI(y = mx +b)\fR
y\-intercept \fI(b)\fR, which happens also to be the first data point on the
graph. \s-1LSLCORREL\s0 is the Correlation Coefficient (also know as Pearson's
Product Moment Correlation Coefficient). It will range from 0 to +/\-1
-and represents the quality of fit for the approximation.
+and represents the quality of fit for the approximation.
.Sp
Example: \f(CW\*(C`VDEF:slope=mydata,LSLSLOPE\*(C'\fR
.SH "SEE ALSO"