![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdgraph_rpn.1 b/doc/rrdgraph_rpn.1
index 8869c4f6b0e95048cd5c9c31813279967ffe95bd..c765dddb3c774c57396ac6dd4fb9cd6d3c76b783 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 v1.37, Pod::Parser v1.14
.\"
.\" 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
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. \*(C+ will
-.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
-.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
-.\" nothing in troff, for use with C<>.
-.tr \(*W-
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. 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 (.SS), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.ie \nF \{\
+.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.el \{\
-. de IX
-..
-.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
.\"
.\" 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.8" "rrdtool"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.if n .ad l
-.nh
+.TH RRDGRAPH_RPN 1 "2009-02-21" "1.3.99909060808" "rrdtool"
.SH "NAME"
rrdgraph_rpn \- About RPN Math in rrdtool graph
.SH "SYNOPSIS"
.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 18
+\& +\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\-!\-\-\->
+\& now
+\& shift 1 t0
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& window
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& shift 2
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& window
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& shift 1 t1
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& window
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& shift 2
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+\& window
+\& <\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
+.Ve
+.Sp
+.Vb 4
+\& 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 behaviour. 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.
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"