X-Git-Url: https://git.verplant.org/?a=blobdiff_plain;ds=sidebyside;f=doc%2Frrdgraph_rpn.pod;h=dfc9a0bda903e77d6538fa7cffe38eb079a4376e;hb=e9fb580fcf041573054e5bcf2184fa7811f9dd59;hp=16c5996c4de33405d6317ade27eee328529f105f;hpb=4b4a568a4322288a7ec2e4b63e4596f76d65b76f;p=rrdtool.git

diff --git a/doc/rrdgraph_rpn.pod b/doc/rrdgraph_rpn.pod
index 16c5996..dfc9a0b 100644
--- a/doc/rrdgraph_rpn.pod
+++ b/doc/rrdgraph_rpn.pod
@@ -1,21 +1,10 @@
 =head1 NAME
 
-rrdtool graph - Round Robin Database tool grapher functions
+rrdgraph_rpn - About RPN Math in rrdtool graph
 
-WARNING: This is for version 1.1.x which is B<I<BETA>> software.
-The software may contain serious bugs. Some of the items
-described in here may not yet exist (although this should
-be mentioned) or still be in the alpha stage.  As with every
-other RRDtool release: use at your own risk.  In contrast with
-the stable version of RRDtool, this release may contain bugs
-known to the authors.  It is highly recommended that you subscribe
-to the mailing list.
+=head1 SYNOPSIS
 
-=head1 SYNOPSYS
-
-I<E<lt>RPN expressionE<gt>> := 
-I<E<lt>vnameE<gt>>|I<E<lt>operatorE<gt>>|I<E<lt>valueE<gt>>
-[ , I<E<lt>RPN expressionE<gt>>]
+I<RPN expression>:=I<vname>|I<operator>|I<value>[,I<RPN expression>]
 
 =head1 DESCRIPTION
 
@@ -23,14 +12,20 @@ If you have ever used a traditional HP calculator you already know
 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 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.
 
-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.
+Example: C<VDEF:maximum=mydata,MAXIMUM>
+
+This will set variable "maximum" which you now can use in the rest
+of your RRD script.
 
 Example: C<CDEF:mydatabits=mydata,8,*>
 
@@ -43,7 +38,7 @@ fact that it is always clear in which order to process the input.
 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
 
@@ -53,27 +48,21 @@ would do C<a = b, 3, +, 5, *> and need no parentheses.
 
 B<LT, LE, GT, GE, EQ, NE>
 
-I<Note: NE is not yet implemented>
-
 Pop two elements from the stack, compare them for the selected condition
 and return 1 for true or 0 for false. Comparing an I<unknown> or an
 I<infinite> value will always result in 0 (false).
 
 B<UN, ISINF>
 
-I<Note: ISINF is not yet implemented>
-
 Pop one element from the stack, compare this to I<unknown> respectively
 to I<positive or negative infinity>. Returns 1 for true or 0 for false.
 
 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 true.
-I<Note: Should this change? It should IMHO as all the other functions
-would return unknown if A,B or C were unknown>
+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)>
 
@@ -81,11 +70,12 @@ Z<>
 
 =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>
 
@@ -109,15 +99,69 @@ B<+, -, *, /, %>
 
 Add, subtract, multiply, divide, modulo
 
-B<SIN, COS, LOG, EXP>
+B<SIN, COS, LOG, EXP, SQRT>
+
+Sine and cosine (input in radians), log and exp (natural logarithm),
+square root.
+
+B<ATAN>
 
-Sine, cosine (input in radians), log, exp (natural logarithm)
+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
+
+B<SORT, REV>
+
+Pop one element from the stack.  This is the I<count> of items to be sorted
+(or reversed).  The top I<count> of the remaining elements are then sorted
+(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 to v6 after removing the smallest and
+largest.
+
+B<TREND>
+
+Create a "sliding window" average of another data series.
+
+Usage:
+CDEF:smoothed=x,1800,TREND
+
+This will create a half-hour (1800 second) sliding window average of x.  The
+average is essentially computed as shown here:
+
+                 +---!---!---!---!---!---!---!---!--->
+                                                     now
+                       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)
 
 =item Special values
 
@@ -138,47 +182,39 @@ set or otherwise the result of this B<CDEF> at the previous time
 step. This allows you to do calculations across the data.  This
 function cannot be used in B<VDEF> instructions.
 
-Z<>
-
-=item Time
+B<PREV(vname)>
 
-Time inside RRDtool is measured in seconds since the epoch. This
-epoch is defined to be S<C<Thu Jan  1 00:00:00 UTC 1970>>.
+Pushes an I<unknown> value if this is the first value of a data
+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.
 
-Z<>
+B<COUNT>
 
-=over 4
+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.
 
-=item NOW
+=item Time
 
-Pushes the current time on the stack.
+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>>.
 
-Z<>
+B<NOW>
 
-=item TIME
+Pushes the current time on the stack.
 
-Pushes the time the currently processed value was taken onto the stack.
+B<TIME>
 
-Z<>
+Pushes the time the currently processed value was taken at onto the stack.
 
-=item LTIME
+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.
-
-=back
-
-For B<VDEF> operations, B<TIME> and B<LTIME> have a different meaning
-I<not yet implemented>.  As the B<VDEF> statement does not work per
-value but rather on a complete time series, there is no such thing as
-the currently processed value.  However, if you have used an operator
-that returned a time component and would like to have this available
-in the value component in stead (so you can use it as a number), you
-can use B<TIME> or B<LTIME> for that.
-
-Z<>
+in the examples section below on how to use this.
 
 =item Processing the stack directly
 
@@ -189,50 +225,71 @@ top elements.
 
 Z<>
 
-=item Selecting characteristics
+=back
 
-These operators work only on B<VDEF> statements.
-I<We can make most of them work at DEF and CDEF statements. If we do
-so, we have a moving (not rolling!) average, max,min etcetera>
+=head1 VARIABLES
 
-Z<>
+These operators work only on B<VDEF> statements. Note that currently ONLY these work for B<VDEF>.
 
 =over 4
 
 =item MAXIMUM, MINIMUM, AVERAGE
 
-Return the corresponding value
+Return the corresponding value, MAXIMUM and MINIMUM also return
+the first occurrence of that value in the time component.
 
-Z<>
+Example: C<VDEF:avg=mydata,AVERAGE>
 
 =item LAST, FIRST
 
-Return the last,first value including its time 
+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.
 
-Z<>
+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
+when you have logged bytes per second. The time component returns
+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.
 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.  I<Inf>inite numbers are lesser, or more, than the
+of them in your data.  B<Inf>inite numbers are lesser, or more, than the
 finite numbers and are always more than the I<Unknown> numbers.
+(NaN E<lt> -INF E<lt> finite values E<lt> INF)
 
 Example: C<VDEF:perc95=mydata,95,PERCENT>
 
-=back
+=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.