![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdgraph_rpn.1 b/doc/rrdgraph_rpn.1
index 8869c4f6b0e95048cd5c9c31813279967ffe95bd..9c600720fd5847476e80e82f5cf7cb986ea959ad 100644 (file)
--- a/doc/rrdgraph_rpn.1
+++ b/doc/rrdgraph_rpn.1
-.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.\" ========================================================================
.\"
.IX Title "RRDGRAPH_RPN 1"
-.TH RRDGRAPH_RPN 1 "2009-02-21" "1.3.8" "rrdtool"
+.TH RRDGRAPH_RPN 1 "2013-05-23" "1.4.8" "rrdtool"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.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
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
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