Introduction:

Ubidots Analytics Engine supports a complex mathematical computation tool called Synthetic Variables. Simply, a variable is any raw or computed data within a device in Ubidots. A "Synthetic Variable" is a variable that results from the computation of other variables within Ubidots.

This tool is very useful to extend your application's functionality, i.e if you develop a temperature logger that reads the variable in °C and you wish to show the data in both °C and °F you would retrieve the sensor change and to send two values to Ubidots: one value in °C and other one in °F. This adds an additional (and unnecessary) compute load to your microcontroller. Using the Ubidots' Analytics Engine you need only send the raw value in °C, and let Ubidots perform the required calculations to convert to ºF, alleviating the excess microcontroller processing requirements.

Synthetic computation example: From Celsius to Fahrenheit

In this article you will learn the basics about Synthetic Variables and the available mathematical and statistical functions you can implement using this tool.

1. Creating a Synthetic Variable
2. Synthetic Mathematical Functions
3. Synthetic Data Range Functions
4. Special Synthetic Functions

Ubidots stores dots that come from your devices as default variables, and these stored dots have corresponding timestamps that organize each dot into a time-series list, using the following sequence:

With Ubidots' Analytics Engine, you can apply different operations to the time-series data-set to create an adjacent data-set containing computed variables; these new variables are called Synthetic Variables.

To create one, simply click on the "Add new variable" option within your device, then select "Synthetic".

2. Synthetic Mathematical Variables

A synthetic mathematical variable consists of a global math operation applied to the whole time-series:

In the figure above, a square root operation is applied to all the time-series. There are several available functions to create mathematical synthetic variables, below you can find a host of commonly used functions:

• `ceil(x)` : Returns the ceiling of x as a integer, the smallest integer value greater than or equal to x.
• `floor(x)` : Returns the floor of x as a integer, the largest integer value less than or equal to x.
• `tan(x)` : Returns the tangent of x radians.
• `cos(x)` : Returns the cosine of x radians.
• `sin(x)` : Returns the sine of x radians.
• `log(x, base)` : Returns the logarithm of x in the specified base (by default base = Euler number).
• `sqrt(x)` : Returns the square root of x.
• `abs(x)` : Returns the absolute value of x.
• `round(x, n digits)` : Returns the floating point value number rounded to "n" digits after the decimal point.

Standard arithmetic operations work just fine too:

• Subtraction: -
• Division: /
• Multiplication: *
• Exponentiation: **
• Module: %

Example:

If you wish to convert from °C to °F, you would implement the function below

``F = ((9 / 5) * raw_variable) + 32``

In your account editor it will look like this:

3. Synthetic Data Range Variable

Ubidots lets you to create new variables from your time-series based in date range data, i.e calculate average temperature per hour or per day based on your sensor's readings using a synthetic variable. Below you can find the commonly used data range functions and formula structure:

• `max(x, data_range)` : Calculates the maximum value of the variable in the specified data range.
• `min(x, data_range)` : Calculates the minimum value of the variable in the specified data range.
• `mean(x, data_range)`: Calculates the mean value of the variable in the specified data range.
• `count(x, data_range)`: Calculates the number of dots received stored in the variable time-series in the specified data range.
• `last(x, data_range)` : Returns the last value of the time-series in the specified data_range.
• `sum(x, data_range)` : Returns the  summation of the dots in the specified data_range.

Available data ranges:

• "nT" : Every n minutes
• "nH" : Every n hours
• "nD" : Every n days
• "W" :  Every end of week
• "M" : Every end of month

Example:

If you wish to know the average °F of your application every 10 minutes, you would implement the function structure below

``A = mean( ((9 / 5) * raw_variable) + 32, "10T" )``

The derived expression editor will look as follows:

Example:

Naturally, every n data range starts its period at 00:00:00, however, there are particular applications where the desire starting point is not 00:00:00 but rather 02:00:00 or 00:40:00, depending on the input data range. To apply an offset, the above functions can receive a third parameter called offset, as follows:

``A = sum(raw_variable, "8H", offset=6)``

The above example corresponds to the sum of raw_variable computed every 8 hours, offset by 6 hours (beyond 00:00:00), that is, 06:00:00. Accordingly, your synthetic variable will be run at 6:00, 14:00, and 22:00 daily.

4. Special Synthetic Functions

There are also some special functions that are suitable to create more complex analytics:

• `where(condition, operation)` :  Performs the operation if the condition is True.
• `fill_missing(x)` : Will enter the last value of a variable when an expression requires data from a timestamp that does not match the other timestamps within the expression.

Examples

• Populates the new synthetic variable with a '1' if the temperature value is greater than 20:
``where({{var}} > 20, 1)``
• Populates the new synthetic variable with a '1' if the temperature value is greater than 20, but on the contrary, fills with '0' if the value is below 20. (ideal for automation applications):
``where({{var}} > 20, 1, 0)``
• Stores the variables' timestamp if it is lower than 10:
``where({{var}} < 20, {{var}}.timestamp)``

this dot, '.' , operator lets you access and represents the variable's timestamp.

• Computes an expression containing multiple variables with different timestamps, filling any non-equal timestamped values with the non-equal variable´s last value.
``fill_missing(3 * var1_id + var2_id)``

Results

Now you're ready to start creating analytics and insights from your data using Ubidots' Analytics Engine using the Synthetic Variable. For additional troubleshoot and inquires, check out the Ubidots Community for assistance from not only Ubidots but also your fellow users who may experience your same errors.

For additional Application Development, do forget to check out:

Ubidots User Management
Ubidots Events Engine
UbiParser - to create your own API