## 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 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 to 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.

**IMPORTANT NOTE:** the synthetic variables engine, although having near real-time update, its computational performance is strongly influenced by the synthetic expression complexity, which renders calculation times between a couple seconds up to a few minutes.

Table of Contents:

- Creating a Synthetic Variable
- List of All Supported Functions
- Mathematical Functions
- Data Range Functions
- Advanced Functions
- Setting Synthetic Variables Timezone

## 1. Creating a Synthetic Variable

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. List of All Supported Functions

CLICK HERE for a PDF containing the complete listing of Ubidots Functions.

## 3. Mathematical Functions

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 an integer, the smallest integer value greater than or equal to x.`floor(x)`

: Returns the floor of x as an integer, the largest integer value less than or equal to x.`tan(x)`

: Returns the tangent of x radians.`tanh(x)`

: Returns the hyperbolic tangent of x radians.`arctan(x)`

: Returns the arctangent of x in radians.`arctanh(x)`

: Returns the hyperbolic arctangent of x in radians.`artan2(y, x)`

: Returns the atan2 of the arguments enter.`cos(x)`

: Returns the cosine of x radians.`cosh(x)`

: Returns the hyperbolic cosine of x radians.`arccos(x)`

: Returns the arccosine of x in radians.`arcosh(x)`

: Returns the hyperbolic arccosine of x in radians.`sin(x)`

: Returns the sine of x radians.`sinh(x)`

: Returns the hyperbolic sine of x radians.`arcsin(x)`

: Returns the arcsine of x radians.`arcsinh(x)`

: Returns the hyperbolic arcsine of x radians`log(x, base)`

: Returns the logarithm of x in the specified base (by default base = Euler number).`exp(x)`

: Return the exponential value of x`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.`shift(x, steps)`

: shifts the values of the variable x by the specified number of steps.`diff(x, steps)`

: Calculated the difference in the specified steps.

Standard arithmetic operations and mathematical constants work just fine too:

**Addition:**+**Subtraction**: -**Division**: /**Multiplication**: ***Exponentiation: ******Module**: %**π :**pi**Euler's number**: e

Example:

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

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

The synthetic editor will look as follows:

## 4. Data Range Functions

Ubidots allows 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.`median(x, data_range)`

: Calculates the median 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.`cumsum(x)`

: Calculates the cumulative sum of the variable x.

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

**IMPORTANT NOTE**: The selected range should be set in a way that evenly divide the next range. For example, if using minutes ("T"), whatever the number is, it has to evenly divide an hour ("H"). Under such example, the available values for minutes are: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30. Other values may render unexpected results. Same applies to other ranges.

**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.

## 5. Advanced Functions

There are additional functions for more complex operations, such as:

#### The "Where" function

`where(condition, operation_if_true, operation_if_false) `

Computes `operation_if_true`

if the condition is True, or `operation_if_false`

if the condition is false.

Comparison statements:

**Equal to:**==**Greater than:**>**Lower than:**<**Not equal to:**!=**Equal to, greater than:**>=**Equal to, lower than:**<=

Logical expressions (useful when setting more than 1 condition):

**And:**"and"**Or:**"or"

**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 20 OR greater than 50:

`where({{var}} < 20 or {{var}} > 50, {{var}}.timestamp)`

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

#### The "Fill Missing" function

`fill_missing(x) `

Computes an expression containing multiple variables with different timestamps, filling any non-equal timestamped values with the non-equal variable´s *last value.*

**Example:**

`fill_missing(3 * var1_id + var2_id)`

#### Retrieve the Context of a Variable

`{YOUR_VARIABLE}.context.context-key`

Context data can only be used within your synthetic expression **if the context is a numerical value**.

#### Retrieve the Timestamp of a Variable

`{YOUR_VARIABLE}.timestamp`

Similar to retrieving context data, you can retrieve the timestamp of a variable using the dot '.' operator.

For more information about advanced functions, check out this article "Analytics: Advanced Synthetic Variables".

## 6. Setting Synthetic Variables Timezone

The synthetic variables editor allows you to select the timezone to reference the exact variable's timestamps based on a particular timezone. This comes in handy when, for example, working with Data Range Functions to calculate a min or max in a day. If your clients are in California but you're assembling the App in Georgia, this timezone in the Synthetic Variable will utilize the correct data based on the timezone selected.

After clicking the "Accept" button, the Synthetic Variable will calculate data as if from the timezone selected and the expression and results will be automatically saved in the history trails of the variable.

## Results

Now you're ready to start creating analytics and insights from your data using Ubidots' Analytics Engine and the **Synthetic Variables. **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.

Other IoT Entrepreneurs also found helpful...

- Analytics: Advanced Synthetic Variables
- Ubidots Events Engine
- UbiFunctions- to create your own API