======== dmproc ======== This is the stream processor engine, which is a fancy name to a component that is able to apply functions over a set of events. It is important to notice that you do not interact with this directly. Rather it is used by other components, like ``xmpp``, to fulfill a user request. Nevertheless, as the functions available here are usually used *as-is* by users through these *higher level* components, the first part of this documentation focuses on the available functions, whereas the second part contains detailed explanation about the protocol. Function syntax =============== Each function contains a name, usually as ascii encoded string, followed by zero or more arguments. For instance, the ``maximum`` function, which computes the maximum value of a set of events, takes no arguments. Operators are the sole exception to this rule, as they are enclosed by parenthesis or brackets. Currently all functions (as well as operators) depends only on the input. They will only produce a result when it receives one or more events. In other words, they are pure functions. You may compose functions using the ``|`` (pipe) operator which resembles greatly the unix pipe operator. So you may think of each function as a combinator and using the pipe operator allow you to grow bigger pipelines. For instance, suppose you have a event that ranges from *0* to *1*, the following function should compute the *mean* of the current set of events and then multiply this value by *100* (left to right application), only returning those *greater than 50*:: mean | (* 100) | [> 50] Operators are always enclosed by parenthesis or brackets. Parenthesis are used for arithmetic operators whereas brackets are used for comparison operators. The syntax allow the operator to be placed either on the left or right side. For instance, ``(/ 100)`` will divide by 100 whereas ``(100 /)`` will divide 100 by the value of the event. The same applies for comparison operators. There are four arithmetic operators defined: ``*``, ``+``, ``-`` and ``/``, which respectively computes the *multiplication*, *addition*, *subtraction* and *division*. And there are six comparison operators defined: ``>`` [greater than], ``<`` [less than], ``>=`` [greater than or equal to], ``<=`` [less than or equal to], ``=`` [equal to] and ``/=`` [not equal to]. Functions reference =================== abs --- Computes the absolute value a number. ceil ---- Smallest integral value that is not less than the current number. floor ----- Largest integral value not greater than the current value. round ----- Round towards infinity. truncate -------- Round towards zero. mean ---- The *mean* of the set of events. sma :n ------ Computes the `simple moving average `_. The actual implementation makes use of ``ewma`` using ``1-2/(n+1)`` as the ``alpha`` parameter. ewma :alpha ----------- Computes the `exponential weighted moving average `_ using :alpha as the *alpha* parameter. **Arguments:** :n: A positive integer number; sample :n/:m ------------ Samples ``n`` elements out from a population of ``m`` items. The exact frequency of elements generated by this function is defined as follows. Let ``L`` the total of elements:: n * (L (mod m)) + minimum n (L (mod m)) **Arguments:** :n: The number of elements pick out of `m`; :m: The so called population size; **Example:**:: sma 30 | sample 1/5 minimum ------- The minimum value. maximum ------- The maximum value. prod ---- Multiplication of all values in the stream. sum --- Summation of all values in the stream. window :n :pipeline ------------------- Creates an window of ``n`` items and when this is full applies a function to produce a result. **Arguments:** :n: An positive integer number [ ``n > 0`` ], which defines the size of the window; :pipeline: The function to apply, enclosed with parenthesis. You may use the pipe to combine multiple functions, and all functions here defined but ``sma``, ``sample`` and ``window``; **Example:**:: window 30 (mean | (* 100)) id -- The identity function: ``id x == x``. Operators reference =================== Arithmetic ---------- :+: Addition (e.g.: ``(+ n)`` or ``(n +)``); :-: Subtraction (e.g.: ``(- n)`` or ``(n -)``); :\*: Multiplication (e.g.: ``(* n)`` or ``(n *)``); :/: Division (e.g.: ``(/ n)`` or ``(n /)``); Comparison ---------- :>: Greater than (e.g: ``[> n]`` or ``[n >]``) :>=: Greater than or equal to (e.g: ``[>= n]`` or ``[n >=]``) :<=: Less than equal to (e.g: ``[<= n]`` or ``[n <=]``) :>: Less than (e.g: ``[< n]`` or ``[< n]``) :=: Equal to (e.g: ``[n =]`` or ``[= n]``) :/=: Not equal to (e.g: ``[n /=]`` or ``[/= n]``)