# User defined analytics ## Objective The analytics processor provides a rich set of features that enable developers to define and execute analytics. This feature is idea for executing an event based analytic expression using attributes present within the event, linked reference data and passed variables. {% hint style="info" %} Currently only Javascript ECMAScript 2024 and Python 3.11 are supported {% endhint %} ## Processor architecture The key analytic processor objective is to provide analytic deployment flexibility for the developer. The ambition is to enable a quick test, learn and refine cycle that reduces time to production deployment.

## Execution models This section covers methods for executing expressions in stream processing, focusing on three key approaches: 1. [**Expression only**](#expression-only)\ Execute independent event-based calculations using simple mathematical formulas by defining core attributes. 2. [**Expression and state**](#expression-and-state)\ Incorporate constants and manage state to initialise calculations and update them with new data. 3. [**Expression and script**](#expression-and-script)\ Leverage pre-existing scripts alongside expressions for more complex calculations. See User Defined Scripts [documentation](https://docs.fractalworks.io/joule/components/analytics/analytic-tools/user-defined-analytics/user-defined-scripts) for script based execution models. ### Expression only When you only want to execute an expression that can be defined as a mathematical formula use this method to execute independent event based calculations provide the expression along with the required core attributes. ```yaml analytic: expression: (bid - ask) / scalar assign to: new_event_variable ``` ### Expression and state This example demonstrates how you would use provided constants for a calculation. This same method can be used to prime a calculation with a starting value for the initial calculation and then being it replaced with updated values by using the same `assign to` variable. See Stateful variables for further [documentation](#stateful-variables). ```yaml analytic: expression: "(ask + (bid - ask) / 2.0) / scaled_price" assign to: scaled_price variables: scaled_price : 120.21 stateful: assign to: scaled_price memory capacity: 1 ``` ### Expression and script Use this option when you have pre-existing scripts which you want to leverage within a stream processing context. ```yaml analytic: script: ./scripts/js/preExistingFunctions.js expression: bid - squareRoot(`${ask}` / `${bid}`) assign to: new_event_variable ``` **Javascript function** The example will apply the `bid` and `ask` event attributes to the expression. Note the current implementation requires the script to be provided using the `js` extension due to the way the expression is defined. {% tabs %} {% tab title="Javascript" %} ```javascript export function squareRoot(num) { if (num < 0) return NaN; return Math.sqrt(num); } ``` {% endtab %} {% tab title="Python" %} ```python import math def square_root(num): if num < 0: return float('nan') # Return NaN for negative input return math.sqrt(num) # Return the square root for non-negative input ``` {% endtab %} {% endtabs %} ## Variables Variables are provided as a map of key and numerical values. Variables and the event are passed in to the execution context per event, including stateful variables. This example demonstrates how to apply a constant as a scaling factor for a calculation. ```yaml analytic: expression: (highest_price - lowest_price) / scaling_factor assign to: scaled_price variables: scaling_factor : 120.21 ``` ## Stateful variables Stateful variables provide a key function whereby the previous value(s) can be used within the current calculation context. The example primes the first calculation with a starting value for the initial calculation and thereafter replaced with the computed values from the stateful memory. This is achieved using the same `assign to` variable set within the `variables` section. ```yaml analytic: expression: (ask + (bid - ask) / 2.0) / Math.avg(scaled_price) assign to: scaled_price variables: scaled_price : 100.00 stateful: assign to: scaled_price memory capacity: 25 ``` ## Attributes schema The follow attributes are used for expression and scripting.

Attribute	Description	Data Type	Required
assign to	Assignment variable for the evaluated expression result	String Default: result	true
variables	Map of constants and seed values for the expression to use. This is an optional variable.	Map<String, Number>	false
stateful	Store previous computed values for next computation cycle	See stateful section	false
assignment datatype	Data type to cast too for the assignment variable. See scripting supported data types section	DataType Default: Double	false

### Execution attributes schema These attributes define what is need to execute analytical functions over a stream events.

Attribute	Description	Data Type
language	Language runtime to use to execute required execution definitions. Currently Javascript (javascript or js) and Python (python or py) are supported	String Default: js
expression	Math expression without an assignment variable. Required if method has not been provided.	String
script	Path of the script to loaded within the Joule processing context	String
function	Function to execute within the provided script using a StreamEvent as a parameter	String
expand all	Add all StreamEvent attributes to the processing context as independ variables	Boolean Default: true
virtualEnv	Python only setting which set the virtual environment path to execute with the script of python expression within.	String

### Stateful attributes schema Store previous computed values for next computation cycle. Honours the groupby definition. The previous computed value can be used on the next calculation.

Attribute	Description	Data Type	Required
assign to	Assignment variable for the result	String	true
memory capacity	Number of rolling elements to store within a FIFO array	Integer Default: 10	false
attach memory	Attach a copy of the array contents to the computed event	Boolean Default: false	false