Function Variables help create new features based on existing variables.

All variables can’t be measured or won’t exist in the data set. The use of function variables will help to bring additional information into the data set. There are many options, so be creative!

For example, if you want to transform a numerical KPI into a symbolic representation, such as quality levels: low, medium, high.

You can also define thresholds, for example if the variable Temp1 is greater than 25 degrees, it is Hot, otherwise Cold. This would be defined in the JavaScript editor as:

if (val("Temp1") > 25) {
	"Hot"} 
	else {"Cold"}

To create a function variable:

Click Transform> Function variable in the menu.
Enter a function Name for the new function variable, for example: Temperature-Average.
Enter a Title. If there is a title the function name is displayed as: Function Name - Title.
Enter a Unit, for example: deg. C.
Select the appropriate Output type: Numeric or Symbolic.
Select Language for the script. Options: JavaScript, Common Lisp, R or Python.
Enter a function Script and add variable from the list as required (Item selection) and click on the Arrow to put them in the script area.
The standard Script is executed for each row, the result is the last evaluated expression.
Click on Template and select from the list of template functions. On the left part of the window, you can see the function. Then click Insert and the script example will be written on the script area. The templates are only available in Javascript.
Click Save.

Function Initializer

The Function Initializer is executed only once, and is intended to put some calculations available for each row such as global counter.

Here there are some of the templates available on the Function Variable.

Template Addition

var a = val("VAR1");
var b = val("VAR2");
a + b + 200;

Template Substraction

var a = val("VAR1");
var b = val("VAR2");
a - b - 200;

Template Multiplication

val("VAR1") * val("VAR2") * 1000

Template Division

val("VAR1") / val("VAR2") / 1000

If-else rule for a symbolic output

var x = val("VAR1");
var y = val("VAR2");
        
if (x == y) {
    'Value if true';
} else {
    'Value if false';
}

If-else rule for numeric output

var x = val("VAR1");
var y = val("VAR2");

if (x >= y) {
    x * y;
} else {
    0.1;
}

Limiting minimum values

Math.min(0, val("VAR"))

Limiting maximum values

Math.max(0, val("VAR"))

For loop

var sum = 0;
for (var i = 0; i < 24; i++) {
    sum = sum + i
}

While loop

var sum = 0;
var i = 0;
while (i < 24) {
    sum = sum + i;
    i++;
}

sum;

Difference between current and previous/next records

// Example 1: Calculate the delta temperature 
// between the current row and the previous row
val("Temperature") - val("Temperature", -1)

// Example 2: Calculate the delta flow between the current
// row and 24 rows ago
val("Flow") - val("Flow", -24)

// NB: The row value (eg. -1 or -24) must go inside the variables brackets but outside 
// the quotation marks with a comma between the variable name and the row value

Last 30 days for symbolic output

// Example 1: last 30 days based on the last available data (for Unix ms time)
var time = val("time");
var timeIndex = table.findAttributeIndex("time");
var lastTime = table.get(table.rowCount() - 1, timeIndex);

(lastTime - time < 30 * 24 * 3600 * 1000) ? 
       "Last month" :
       "Prior to last month" 

//Example 2: Last 30 days based on today’s date (for Unix ms time)
var time = val("time");
var timeIndex = table.findAttributeIndex("time");
var lastTime = new Date().getTime();

(lastTime - time < 30 * 24 * 3600 * 1000) ?
       "Last month" :
       "Prior to last month"

Specific enthalpy as a function of pressure & temperature

// Example 1: Metric (specific enthalpy in kJ/kg)
var press1 = val("PRESS_VAR") // (bar absolute)
var temp1 = val("TEMP_VAR ") // (deg C)
if97.specificEnthalpyPT(press1, temp1)

// Example 2: Imperial (specific enthalpy in BTU/lb)
var press2 = val("PRESS_VAR") // (psi absolute) 
var temp2 = val("TEMP_VAR") // (deg F)
if97_IMP.specificEnthalpyPT(press2, temp2)

// For more information refer to the if97 
// library documentation :
// http://if97.sourceforge.net/javadoc/

Specific enthalpy as a function of pressure for saturated liquid

// Example 1: Metric (specific enthalpy in kJ/kg)
var barAbsolute = val("PRESS_BAR_VAR")
if97.specificEnthalpySaturatedLiquidP(barAbsolute)

// Example 2: Imperial (specific enthalpy in BTU/lb)
var psiAbsolute = val("PRESS_PSI_VAR")
if97_IMP.specificEnthalpySaturatedLiquidP(psiAbsolute);

// For more information refer to the if97 
// library documentation: 
// http://if97.sourceforge.net/javadoc/

Specific enthalpy as a function of temperature for saturated liquid

// Example 1: Metric (specific enthalpy in kJ/kg)
var barAbsolute = val("PRESS_BAR_VAR")
if97.specificEnthalpySaturatedLiquidP(barAbsolute)

// Example 2: Imperial (specific enthalpy in BTU/lb)
var psiAbsolute = val("PRESS_PSI_VAR")
if97_IMP.specificEnthalpySaturatedLiquidP(psiAbsolute);

// For more information refer to the if97 
// library documentation: 
// http://if97.sourceforge.net/javadoc/

Lisp Language

Function variables can be written in Common Lisp in the editor. For more information on Common Lisp, see Common Lisp.

Javascript language

Function variables can be written in JavaScript in the editor. Several template examples are shown above. For more information on Javascript, see JavaScript.

Template to calculate the difference between previous and current values of tanks level

// this example detects if a tank is being filled with product 
var a = val("Tank level") - val("Tank level",-1) // difference between previous and present values of the tank level 
if (a<=0){
    0 
} else {
    a
}

Template to handle null values in Function Variables

//The script describes how to add two variables that have too many missing values. 
It might happen that the sum turns out to be null, since in cases there is a value and null the result is null. 
So, to solve this problem the null value have to be considered as zero. 
To explicit that check the script below: 

var tag1 = val ("power 1");
var tag2 = val ("power 2");
if (!tag1) {// if tag1 equals null then replace it by 0 
     tag1=0;
}
if (!tag2) {// if tag2 equals null then replace it by 0 
     tag2=0;
}

Note: Some model (linear regression and decision trees, for example) can be exported as function variables.

Python language

Function variables can be written in Python in the editor. For more information on Python, see Python.

Standard script with initializer

// Example: The function initializer defines the function offset2 that returns the square of x. 
It is executed only once and it is intended to put some calculations available for each row, such as global counter. 
The standard script (value of variables power - offset2) is executed for each row. 
The result is the last evaluated expression.

val("power") - offset2() 

with initializer written as

def offset2(x=0):
   return x * 2

R language

Function variables can be written in R in the editor. For more information on R, see R.

Template to return the value of a variable

val("power")

Note: val (& valEx) method are available in the 3 languages and return the specified variable value of the current row

Template to searche which type of product the plant is manufacturing.

// check if product A
if (val("Tag1") !== "OK" && val("Tag2") !== "KO"){
"product A"}

External libraries

In order to compute function variables, several external libraries are included in DATAmaestro Analytics. IF97 is used to compute steam/water properties and CoolProp library is used to computes properties of fluid and humid air.

IF97 library

This library provides steam tables for industrial use according to the international standard for the properties of water and steam, the IAPWS-IF97 formulation and the international standards for transport and other properties.

Example of IF97 code

#This code computes the specific enthalpy of steam given pressure and temperature of steam
if97.specificEnthalpyPT(val("Pressure"),val("Temperature"))

The if97 library uses the Engineering units system. Units that are commonly used in process engineering practice. There is also the possibility of using the library if97_IMP that uses the British Imperial system of units. For more information about the Refer Unit System, see IF97.UnitSystem.

For more information, see Javadoc IF97 library

Check some of the templates below:

Specific enthalpy as function of pressure and temperature

// Example 1: Metric (specific enthalpy in kJ/kg)
var press1 = val("PRESS_VAR") // (bar absolute)
var temp1 = val("TEMP_VAR ") // (deg C)
if97.specificEnthalpyPT(press1, temp1)

// Example 2: Imperial (specific enthalpy in BTU/lb)
var press2 = val("PRESS_VAR") // (psi absolute) 
var temp2 = val("TEMP_VAR") // (deg F)
if97_IMP.specificEnthalpyPT(press2, temp2)

// For more information refer to the if97 
// library documentation :
// http://if97.sourceforge.net/javadoc/

Specific enthalpy as a function of pressure for saturated liquid

// Example 1: Metric (specific enthalpy in kJ/kg)
var barAbsolute = val("PRESS_BAR_VAR")
if97.specificEnthalpySaturatedLiquidP(barAbsolute)

// Example 2: Imperial (specific enthalpy in BTU/lb)
var psiAbsolute = val("PRESS_PSI_VAR")
if97_IMP.specificEnthalpySaturatedLiquidP(psiAbsolute);

// For more information refer to the if97 
// library documentation: 
// http://if97.sourceforge.net/javadoc/

Specific enthalpy as a function of temperature for saturated liquid

// Example 1: Metric (specific enthalpy in kJ/kg)
var tempCel = val("CELSIUS_VAR") // (deg C)
if97.specificEnthalpySaturatedLiquidT(tempCel)


// Example 2: Imperial (specific enthalpy in BTU/lb)
var tempFar = val("FARH_VAR") // (deg F)
if97_IMP.specificEnthalpySaturatedLiquidT(tempFar)

// For more information refer to the if97 
// library documentation: 
// http://if97.sourceforge.net/javadoc/

Coolprop library

CoolProp is an open-source database of fluid and humid air properties, formulated based on the most accurate formulations in open literature. It has been validated against the most accurate data available from the relevant references.

CoolProp is a library that implements:

Example of Coolprop code

#Saturation temperature of Water at 1 atm in K
coolProp.PropsSI('T','P',101325,'Q',0,'Water')

Other examples on how to use the "Coolprop" library are available here Examples of using CoolProp library

A paper covering CoolProp has been published in the Journal Industrial & Engineering Chemistry Research (link to paper) with an OpenAccess license.