implicitly, so whenever you specify a number or a variable, it gets
pushed onto the stack automatically.
-At the end of the calculation there should be one and only one
-value left on the stack. This is the outcome of the function and
-this is what is put into the I<vname>. For B<CDEF> instructions,
-the stack is processed for each data point on the graph. B<VDEF>
-instructions work on an entire data set in one run.
+At the end of the calculation there should be one and only one value left on
+the stack. This is the outcome of the function and this is what is put into
+the I<vname>. For B<CDEF> instructions, the stack is processed for each
+data point on the graph. B<VDEF> instructions work on an entire data set in
+one run. Note, that currently B<VDEF> instructions only support a limited
+list of functions.
Example: C<VDEF:maximum=mydata,MAXIMUM>
Example: C<CDEF:mydatabits=mydata,8,*>
This means: push variable I<mydata>, push the number 8, execute
-the operator I<+>. The operator needs two elements and uses those
+the operator I<*>. The operator needs two elements and uses those
to return one value. This value is then stored in I<mydatabits>.
As you may have guessed, this instruction means nothing more than
I<mydatabits = mydata * 8>. The real power of B<RPN> lies in the
Add, subtract, multiply, divide, modulo
+B<ADDNAN>
+
+NAN-safe addition. If one parameter is NAN/UNKNOWN it'll be treated as
+zero. If both parameters are NAN/UNKNOWN, NAN/UNKNOWN will be returned.
+
B<SIN, COS, LOG, EXP, SQRT>
Sine and cosine (input in radians), log and exp (natural logarithm),
Convert angle in degrees to radians, or radians to degrees.
+B<ABS>
+
+Take the absolute value.
+
=item Set Operations
B<SORT, REV>
compute the average of the values v1 to v6 after removing the smallest and
largest.
-B<TREND>
+B<AVG>
+
+Pop one element (I<count>) from the stack. Now pop I<count> elements and build the
+average, ignoring all UNKNOWN values in the process.
+
+Example: C<CDEF:x=a,b,c,d,4,AVG>
+
+B<TREND, TRENDNAN>
Create a "sliding window" average of another data series.
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)
+TRENDNAN is - in contrast to TREND - NAN-safe. If you use TREND and one
+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.
+
+B<PREDICT, PREDICTSIGMA>
+
+Create a "sliding window" average/sigma of another data series, that also
+shifts the data series by given amounts of of time as well
+
+Usage - explicit stating shifts:
+CDEF:predict=<shift n>,...,<shift 1>,n,<window>,x,PREDICT
+CDEF:sigma=<shift n>,...,<shift 1>,n,<window>,x,PREDICTSIGMA
+
+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
+
+Example:
+CDEF:predict=172800,86400,2,1800,x,PREDICT
+
+This will create a half-hour (1800 second) sliding window average/sigma of x, that
+average is essentially computed as shown here:
+
+ +---!---!---!---!---!---!---!---!---!---!---!---!---!---!---!---!---!--->
+ 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)
+
+
+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...
+
+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.
+
+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
+
+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 "noisy" the data series is.
+
+This prediction can only be used for short term extrapolations - say a few days into the future-
+
=item Special values
B<UNKN>
you to make calculations based on the position of the value within
the data set. This function cannot be used in B<VDEF> instructions.
-Z<>
-
=item Time
Time inside RRDtool is measured in seconds since the epoch. The
=head1 VARIABLES
-These operators work only on B<VDEF> statements.
+These operators work only on B<VDEF> statements. Note that currently ONLY these work for B<VDEF>.
=over 4
Example: C<VDEF:avg=mydata,AVERAGE>
+=item STDEV
+
+Returns the standard deviation of the values.
+
+Example: C<VDEF:stdev=mydata,STDEV>
+
=item LAST, FIRST
Return the last/first value including its time. The time for
Example: C<VDEF:total=mydata,TOTAL>
-=item PERCENT
+=item PERCENT, PERCENTNAN
This should follow a B<DEF> or B<CDEF> I<vname>. The I<vname> 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
I<percentage> percent of the values is lower or equal than the result.
+For PERCENTNAN I<Unknown> values are ignored, but for PERCENT
I<Unknown> values are considered lower than any finite number for this
purpose so if this operator returns an I<unknown> you have quite a lot
of them in your data. B<Inf>inite numbers are lesser, or more, than the
(NaN E<lt> -INF E<lt> finite values E<lt> INF)
Example: C<VDEF:perc95=mydata,95,PERCENT>
+ C<VDEF:percnan95=mydata,95,PERCENTNAN>
=item LSLSLOPE, LSLINT, LSLCORREL
=head1 AUTHOR
-Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
+Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>
projects / rrdtool.git / blobdiff