diff --git a/doc/rrdgraph_rpn.html b/doc/rrdgraph_rpn.html
index bed66325f395102095325ac47665002bb4ccf7c1..35097c81201b2fdd77a6d145d082d61cd97a67a3 100644 (file)
--- a/doc/rrdgraph_rpn.html
+++ b/doc/rrdgraph_rpn.html
<p><strong>LT, LE, GT, GE, EQ, NE</strong></p>
<p>Pop two elements from the stack, compare them for the selected condition
and return 1 for true or 0 for false. Comparing an <em>unknown</em> or an
-<em>infinite</em> value will always result in 0 (false).</p>
+<em>infinite</em> value will result in <em>unknown</em> returned ... which will also be
+treated as false by the <strong>IF</strong> call.</p>
<p><strong>UN, ISINF</strong></p>
<p>Pop one element from the stack, compare this to <em>unknown</em> respectively
to <em>positive or negative infinity</em>. Returns 1 for true or 0 for false.</p>
source value is NAN the complete sliding window is affected. The TRENDNAN
operation ignores all NAN-values in a sliding window and computes the
average of the remaining values.</p>
+<p><strong>PREDICT, PREDICTSIGMA</strong></p>
+<p>Create a "sliding window" average/sigma of another data series, that also
+shifts the data series by given amounts of of time as well</p>
+<p>Usage - explicit stating shifts:
+CDEF:predict=<shift n>,...,<shift 1>,n,<window>,x,PREDICT
+CDEF:sigma=<shift n>,...,<shift 1>,n,<window>,x,PREDICTSIGMA</p>
+<p>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</p>
+<p>Example:
+CDEF:predict=172800,86400,2,1800,x,PREDICT</p>
+<p>This will create a half-hour (1800 second) sliding window average/sigma of x, that
+average is essentially computed as shown here:</p>
+<pre>
+ +---!---!---!---!---!---!---!---!---!---!---!---!---!---!---!---!---!--->
+ now
+ shift 1 t0
+ <----------------------->
+ window
+ <--------------->
+ shift 2
+ <----------------------------------------------->
+ window
+ <--------------->
+ shift 1 t1
+ <----------------------->
+ window
+ <--------------->
+ shift 2
+ <----------------------------------------------->
+ window
+ <---------------></pre>
+<pre>
+ 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)</pre>
+<p>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...</p>
+<p>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.</p>
+<p>rrdtool graph image.png --imgformat=PNG \
+ --start=-7days --end=+3days --width=1000 --height=200 --alt-autoscale-max \
+ DEF:value=value.rrd:value:AVERAGE:start=-14days \
+ LINE1:value#ff0000:value \
+ CDEF:predict=86400,-7,1800,value,PREDICT \
+ CDEF:sigma=86400,-7,1800,value,PREDICTSIGMA \
+ CDEF:upper=predict,sigma,3,*,+ \
+ CDEF:lower=predict,sigma,3,*,- \
+ LINE1:predict#00ff00:prediction \
+ LINE1:upper#0000ff:upper\ certainty\ limit \
+ LINE1:lower#0000ff:lower\ certainty\ limit \
+ CDEF:exceeds=value,UN,0,value,lower,upper,LIMIT,UN,IF \
+ TICK:exceeds#aa000080:1</p>
+<p>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 "noisy" the data series is.</p>
+<p>This prediction can only be used for short term extrapolations - say a few days into the future-</p>
</dd>
<dt><strong><a name="special_values" class="item">Special values</a></strong></dt>
<dt><strong><a name="last_first" class="item">LAST, FIRST</a></strong></dt>
<dd>
-<p>Return the last/first value including its time. The time for
-FIRST is actually the start of the corresponding interval, whereas
-LAST returns the end of the corresponding interval.</p>
+<p>Return the last/first non-nan or infinite value for the selected data
+stream, including its timestamp.</p>
<p>Example: <code>VDEF:first=mydata,FIRST</code></p>
</dd>
<dt><strong><a name="total" class="item">TOTAL</a></strong></dt>
<dd>
<p>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.</p>
<p>Example: <code>VDEF:total=mydata,TOTAL</code></p>
</dd>
-<dt><strong><a name="percent" class="item">PERCENT</a></strong></dt>
+<dt><strong><a name="percent_percentnan" class="item">PERCENT, PERCENTNAN</a></strong></dt>
<dd>
<p>This should follow a <strong>DEF</strong> or <strong>CDEF</strong> <em>vname</em>. The <em>vname</em> 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
<em>percentage</em> percent of the values is lower or equal than the result.
+For PERCENTNAN <em>Unknown</em> values are ignored, but for PERCENT
<em>Unknown</em> values are considered lower than any finite number for this
purpose so if this operator returns an <em>unknown</em> you have quite a lot
of them in your data. <strong>Inf</strong>inite numbers are lesser, or more, than the
finite numbers and are always more than the <em>Unknown</em> numbers.
(NaN < -INF < finite values < INF)</p>
-<p>Example: <code>VDEF:perc95=mydata,95,PERCENT</code></p>
+<p>Example: <code>VDEF:perc95=mydata,95,PERCENT</code>
+ <code>VDEF:percnan95=mydata,95,PERCENTNAN</code></p>
</dd>
<dt><strong><a name="lslslope_lslint_lslcorrel" class="item">LSLSLOPE, LSLINT, LSLCORREL</a></strong></dt>