-=head1 NAME
+=head1 NAME
rrdgraph_rpn - About RPN Math in rrdtool graph
B<RPN>. The idea behind B<RPN> is that you have a stack and push
your data onto this stack. Whenever you execute an operation, it
takes as many elements from the stack as needed. Pushing is done
-implicit so whenever you specify a number or a variable, it gets
-pushed automatically.
+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 exactly 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
For expressions like C<a = b + 3 * 5> you need to multiply 3 with
5 first before you add I<b> to get I<a>. However, with parentheses
you could change this order: C<a = (b + 3) * 5>. In B<RPN>, you
-would do C<a = b, 3, +, 5, *> and need no parentheses.
+would do C<a = b, 3, +, 5, *> without the need for parentheses.
=head1 OPERATORS
B<IF>
-Pops three elements from the stack. If the last element is 0 (false),
-the first value is pushed back onto the stack, otherwise the second
-popped value is pushed back. This does, indeed, mean that any value
-other than 0 is considered to be true.
+Pops three elements from the stack. If the element popped last is 0
+(false), the value popped first is pushed back onto the stack,
+otherwise the value popped second is pushed back. This does, indeed,
+mean that any value other than 0 is considered to be true.
Example: C<A,B,C,IF> should be read as C<if (A) then (B) else (C)>
=item Comparing values
-B<MIN, MAX>
+B<MIN, MAX>
-Pops two elements from the stack and returns the lesser or larger.
-The two numbers shouldn't be I<infinite> or I<unknown>, if they are
-that value is pushed back onto the stack as the result.
+Pops two elements from the stack and returns the smaller or larger,
+respectively. Note that I<infinite> is larger than anything else.
+If one of the input numbers is I<unknown> then the result of the operation will be
+I<unknown> too.
B<LIMIT>
B<SIN, COS, LOG, EXP, SQRT>
-Sine, cosine (input in radians), log, exp (natural logarithm), square root
+Sine and cosine (input in radians), log and exp (natural logarithm),
+square root.
B<ATAN>
-Arctangent. Output in radians.
+Arctangent (output in radians).
+
+B<ATAN2>
+
+Arctangent of y,x components (output in radians).
+This pops one element from the stack, the x (cosine) component, and then
+a second, which is the y (sine) component.
+It then pushes the arctangent of their ratio, resolving the ambiguity between
+quadrants.
+
+Example: C<CDEF:angle=Y,X,ATAN2,RAD2DEG> will convert C<X,Y>
+components into an angle in degrees.
B<FLOOR, CEIL>
-Round down,up to the nearest integer
+Round down or up to the nearest integer.
-Z<>
+B<DEG2RAD, RAD2DEG>
+
+Convert angle in degrees to radians, or radians to degrees.
=item Set Operations
(or reversed) in place on the stack.
Example: C<CDEF:x=v1,v2,v3,v4,v5,v6,6,SORT,POP,5,REV,POP,+,+,+,4,/> will
-compute the average of the values v1..v6 after removing the smallest and
+compute the average of the values v1 to v6 after removing the smallest and
largest.
B<TREND>
delay t0
<--------------->
delay t1
- <--------------->
+ <--------------->
delay t2
<--------------->
- 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)
+ 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)
=item Special values
B<PREV(vname)>
Pushes an I<unknown> value if this is the first value of a data
-set or otherwise the result of vname variable at the previous time
-step. This allows you to do calculations across the data. This
+set or otherwise the result of the vname variable at the previous time
+step. This allows you to do calculations across the data. This
function cannot be used in B<VDEF> instructions.
B<COUNT>
-Pushes the number 1 if this is the first value of the data set, the
-number 2 if it is the second, and so on. This special value, allows
-you to make calculations based on the position of the value within
+Pushes the number 1 if this is the first value of the data set, the
+number 2 if it is the second, and so on. This special value allows
+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. This
+Time inside RRDtool is measured in seconds since the epoch. The
epoch is defined to be S<C<Thu Jan 1 00:00:00 UTC 1970>>.
B<NOW>
B<TIME>
-Pushes the time the currently processed value was taken onto the stack.
+Pushes the time the currently processed value was taken at onto the stack.
B<LTIME>
Takes the time as defined by B<TIME>, applies the time zone offset
valid at that time including daylight saving time if your OS supports
it, and pushes the result on the stack. There is an elaborate example
-in the examples section on how to use this.
+in the examples section below on how to use this.
=item Processing the stack directly
=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
=item LAST, FIRST
-Return the last,first value including its time. The time for
-FIRST is actually the start of the corresponding interval, where
-the LAST time component returns the end of the corresponding interval.
+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.
Example: C<VDEF:first=mydata,FIRST>
=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 transfered
when you have logged bytes per second. The time component returns
-the amount of seconds
+the number of seconds.
Example: C<VDEF:total=mydata,TOTAL>
=item PERCENT
-Should follow a B<DEF> or B<CDEF> I<vname>. This I<vname> is popped,
+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.
Example: C<VDEF:perc95=mydata,95,PERCENT>
+=item LSLSLOPE, LSLINT, LSLCORREL
+
+Return the parameters for a B<L>east B<S>quares B<L>ine I<(y = mx +b)>
+which approximate the provided dataset. LSLSLOPE is the slope I<(m)> of
+the line related to the COUNT position of the data. LSLINT is the
+y-intercept I<(b)>, which happens also to be the first data point on the
+graph. LSLCORREL 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.
+
+Example: C<VDEF:slope=mydata,LSLSLOPE>
+
=back
=head1 SEE ALSO
L<rrdgraph> gives an overview of how B<rrdtool graph> works.
-L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
-L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
+L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
+L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
L<rrdgraph_graph> page describes all of the graph and print functions.
Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
=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