Understanding Models

Models

A model is a container which can have a network of blocks connected to each other with wires.

The behavior of a block inside a model does not depend on other blocks. There can be multiple instances of the same block in a model where each instance may behave differently, depending on the configurable parameters or the inputs connected to the block.

Blocks

Blocks are the basic processing units of the model. Each block has some predefined functionality and processes data accordingly. A block can have a set of parameters and a set of input ports and output ports.

The palette of the model editor offers for selection the following types of blocks:

A block can receive data from another block through its input ports. A block can send data to another block through its output ports. Different blocks will have different numbers of input or output ports, and some blocks have only input ports or only output ports. For most blocks, it is not required to connect all of the input or output ports.

A block can have configurable parameters that define the behavior of the block. These parameters are either optional or mandatory, depending on the requirement of the block.

When using the same block multiple times, you can specify different values for the same parameter. For example, the Threshold block has a configurable parameter named Threshold Value. If you are using two instances of the Threshold block and configure this parameter differently for each block, the blocks will report different breaches of the threshold.

Note: Two output ports cannot be connected to same input port, whereas one output port can be connected to multiple input ports.

Input blocks

An input block is a special type of block that receives data from an external source. It converts the data into a format understandable to wires and transfers the data to the connected blocks. For example, when an input block receives a Measurement event from Cloud of Things, it extracts the required information from the event and then transfers the information to the connected blocks for further processing.

Models can process data from multiple devices, and scale up (using multiple cores) when doing so. For detailed information, see Model execution for different devices.

In addition, Analytics Builder supports input devices that are referred to as “broadcast devices”. Signals from these devices are available to all models across all devices. For detailed information, see Broadcast devices.

Output blocks

An output block is a special type of block that receives data from a connected processing block. It converts the data into a format understandable to an external source and transfers the data to the external source. For example, when an output block receives data from a connected processing block, it packages the data into an Operation object and then sends the operation to Cloud of Things.

The Trigger Device is a special output block which can be used to send the output back to the device which triggered the output. Models can process data from multiple devices, and scale up (using multiple cores) when doing so. For detailed information, see Model execution for different devices.

Processing blocks

There are different types of processing blocks. They are grouped into different categories in the palette in the model editor, depending on their functionality.

This category includes blocks that
Logic perform logical operations on the data. Blocks such as AND and OR are in this category.
Calculation perform mathematical operations on the data. Blocks such as Difference, Threshold, Direction Detection, Delta and Expression are in this category.
Aggregate perform aggregation of the data over a window of values. Blocks such as Average (Mean) and Integral are in this category.
Flow Manipulation manipulate the flow of the data. Blocks such as Time Delay, Gate, Pulse and Latch Values are in this category.
Utility provide miscellaneous utility functions. Blocks such as Toggle and Missing Data are in this category.

Example of a processing block - the Threshold block

The following example shows what a block looks like in the model editor, together with the block parameter editor. It shows the Threshold block, which detects whether the input value breaches the threshold or whether it crosses the threshold.

The parameters are:

The input ports are:

The output ports are:

Overview of all blocks

The following table gives a brief description of all blocks that can be selected from the palette of the model editor, sorted alphabetically.

Block name Description
AND Performs a logical ‘and’ on the inputs.
Average (Mean) Calculates the mean of the values over time.
Combiner Calculates the output based on the selected mode and the connected inputs.
Crossing Counter Detects and counts the number of threshold crossings in the specified direction.
Delta Calculates the difference between successive input values.
Difference Calculates the absolute and signed differences between the connected inputs.
Direction Detection Detects whether the input value changes direction.
Expression Evaluates an expression to perform arithmetic or logical calculations or string operations.
Extract Property Extracts the specified property from the input value and converts it to the specified type.
Gate Blocks the input from going to output unless the gate is open and enabled.
Gradient Calculates the weighted linear regression gradient for the values.
Input Input block for measurements or other inputs from a device or device group.
Integral Calculates the integral of the input value over time.
Latch Values Latches the latest input value received while the block is enabled.
Minimum / Maximum Calculates the minimum and maximum of a value over time.
Missing Data Generates an output if the input has not occurred for a set amount of time.
NOT Performs a logical ‘not’ on the input.
OR Performs a logical ‘or’ on the inputs.
Output Output block for creating measurements or other outputs for a device (or the triggering device).
Pulse Converts a non-pulse input into a pulse output.
Range Lookup Finds the range in which the input value lies.
Rounding Rounds the input to a specified number of decimal points or to an integer, using a selectable rule.
Standard Deviation Calculates the standard deviation and variance of the values over time.
Threshold Compares the input value against the defined threshold value to detect whether the input breaches the threshold or whether it crosses the threshold.
Time Delay Delays the input by the specified amount of time.
Toggle Converts two pulse inputs to a boolean output based on the set and reset signals, with optional delays.

Creating your own blocks

You can use the Analytics Builder Block SDK to write, test, and package custom blocks and to upload these blocks into Analytics Builder.

The Block SDK is available from GitHub at https://github.com/SoftwareAG/apama-analytics-builder-block-sdk. See the documentation in GitHub for detailed information.

You write the custom blocks in Apama’s Event Processing Language (EPL). Once you have written a block, you can package it into an extension and upload it. An example command line to build and upload an extension is:

analytics_builder build extension --input path --cumulocity_url $C8Y_URL --username $C8Y_USERNAME --password $C8Y_PASSWORD --name customBlocks

Wires

One block is connected to another block with the help of wires. All data transfer between the output port of one block and the input port of another block is done using wires. All connections must be made between compatible types. See Wires and Blocks for detailed information.

Note: The network of blocks in a model cannot contain any kind of cycles. See Wire restrictions for more information.

Sample use case

Consider a situation where you are getting real-time sensor data and you want to analyze this data. For the sake of simplicity, let us assume that there is only one sensor and that you are interested in the following:

The model for this example has the following blocks: