====== Statistical operators in HMR ======
Statistical operators can be used in decision part of the rule or in the right-hand side of the conditional formulae of the rule.
They are used to capture dynamics and temporal changes in attributes values.
They cannot be combined with [[pub:software:heartdroid:tutorials:tbo|time-parametrized operators]], however they are themselves time-parametrized.

===== Use case =====
The use case scenario described in this section is a very (very) simple model of a bot that decided weather to sell or not to sell shares on a stock.

The simplest model will monitor the price, and if the current price is high enough to satisfy previously defined threshold -- sell.
Otherwise, withhold until the price go up (if ever).

The more advanced (yes still very simple) model would monitor how the price changes to optimize the profit.
For instance even if the current price satisfy the profit threshold, but the price is still going up -- do not sell, but wait for even better price instead.

The second model requires some statistical analysis of historical data.
And this is where statistical functions come in handy.

The model described above is presented in the following Figure.
See table ''calculateTrend'', which uses a ''trend'' function in its decision part.
The ''trend'' function has two parameters:
  * attribute name over values of which all the calculations will be performed
  * relative time period from which the historical values of an attribute should be taken into calculations. This time period is given in the same format as in case of [[pub:software:heartdroid:tutorials:tbo|time-parametrized operators.]]

{{:pub:software:heartdroid:tutorials:stock-model.png|}}

The full model with sample test [[pub:software:heartdroid:tutorials:haquna|HaQuNa]] script can be downloaded form {{:pub:software:heartdroid:tutorials:stock-seller.zip|here}}.
The zip file has a model (''*stock-seller.hmr'' file) and two scripts:
  * ''stock-seller-simple.hqn'', that uses [[pub:software:heartdroid:tutorials:inference_config|FOI inference mode]] to obtain a value of the attributes that ''simpleSell'' table is producing. It does not use the statistical function ''trend''
  * ''stock-seller-trend.hqn'', that uses [[pub:software:heartdroid:tutorials:inference_config|FOI inference mode]] to obtain a value of the attribute that ''trendBasedSell'' is producing. The decision whether sell or not sell is made based on the analysis of the historical prices.

Note, that in both cases we used [[pub:software:heartdroid:tutorials:inference_config|FOI inference mode]].
This is because we used so called //looped-tbles//, i.e. tables that uses the same attributes in conditional and delusional parts, which may cause errors while using GDI or DDi inference mode.

To run the scripts you will need the latest version of [[pub:software:heartdroid:tutorials:haquna|HaQuNa commandline shell]].
To run the first script use the following command:
<code bash>
java -cp haquna.jar:. haquna.HaqunaMain --console stock-seller-simple.hqn
</code>
After running the script you should get the output that looks similar to the following one:
<code>
Attribute: real_profit_ratio  	= 0.8099999999999998  	 cf = 1.0
Attribute: sell_price  	= 200.0  	 cf = 1.0
Attribute: price_trend  	= null  	 cf = 1.0
Attribute: price  	= 211.0  	 cf = 1.0
Attribute: sell  	= true  	 cf = 1.0
Attribute: buy_price  	= 100.0  	 cf = 1.0
Attribute: total_profit  	= 100.0  	 cf = 1.0
Attribute: profit_ratio  	= 2.11  	 cf = 1.0
Attribute: desired_profit_ratio  	= 1.3  	 cf = 1.0
</code>
Note, that the ''sell'' attribute is set to true, so the item was sold, and the ''sell_price'' is set to 200, which means that the system sold the item immediately after the price exceeded the desired profit.

To run the second script use the following command:
<code bash>
java -cp haquna.jar:. haquna.HaqunaMain --console stock-seller-trend.hqn
</code>

After running the script you should get the output that looks similar to the following one:
<code>
Attribute: real_profit_ratio  	= 0.8099999999999998  	 cf = 1.0
Attribute: sell_price  	= null  	 cf = 1.0
Attribute: price_trend  	= 1.3621621621621627  	 cf = 1.0
Attribute: price  	= 211.0  	 cf = 1.0
Attribute: sell  	= false  	 cf = 1.0
Attribute: buy_price  	= 100.0  	 cf = 1.0
Attribute: total_profit  	= 0.0  	 cf = 1.0
Attribute: profit_ratio  	= 2.11  	 cf = 1.0
Attribute: desired_profit_ratio  	= 1.3  	 cf = 1.0
</code>

Note, that the system did not sell the item despite the price is high above the desired profit ratio.
This is because the price is still growing.

In the second script, try to manipulate with values of price over time. 
For instance see what will happen if you start decreasing prices.

===== Statistical operators for nominal and numerical attributes =====
^ Syntax ^ Description ^
|''valat(Attr, Time)''| Returns value of an attribute at the given moment of time. |
|''var(Attr, Period)''|In case of numeric attribute, returns variance of the  attribute’s values from specified period of time. In case of symbolic type, variance is replaced with entropy.|
|''mode(Attr, Period)''|Returns set of the most frequent attribute’s values from specified period of time|
===== Statistical operators only for numerical attributes =====

^ Syntax ^ Description ^
|''max(Attr, Period)''|Returns the biggest value of an attribute from specified period of time.|
|''min(Attr, Period)''|Returns the smallest value of an attribute from specified period of time.|
|''mean(Attr, Period)''|Returns mean of the attribute’s values from specified period of time.|
|''med(Attr, Period)''|Returns median of the attribute’s values from specified period of time.|
|''stddev(Attr, Period)''|Returns standard deviation of the attribute’s values from specified period of time.|
|''trend(Attr, Period)''|Returns slope of the trend line fitted to attribute’s values using the least–squares fit.|