========
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]``)