Formula Interpreter 1 - Introduction¶
The formula interpreter can be used to calculate new channels and add them to a given NC file. Example: If a file contains the channels speed and torque, a new channel power =(speed * torque) / 9549.3 can be calculated. If speed or torque values are edited, dependent channels can be updated.
If data of the speed or torque channel is modified, the formula interpreter can update the dependent channels.
For MDF-, Famos- or ASAM-ODS-Data the formula can contain channels with different number of data points. In this case the formula interpreter will interpolate all used channels to the time base of the first specified data channel.
For all other data files the number of data points of all channel used in a formula must contain the identical number of data points. The result of the formula is a channel the the same number of data points. Global file attributes can be used in the formula, for example displacement = 2000. If a formula does not contain any channels the formula channel will be added to the channel group of the fist channel in the NC file (Channel with dimid=0).
An Example¶
Import the data file test1.xls from the directory c:\Program Files\UniPlot\Samples. Click on the >> button to fully open the data browser:
Right click on a channel name in the data grid and choose the command Add Formula Channel to open the following dialog box:
Type the following formula into the text field:
Power = (EngSpd * SAETrq)/9550
The formula creates the channel Power.
Click OK to add the channel to the NC file.
The Add Formula Channel Dialog Box¶
- Saved Formulas
- This combo box lists the last 128 formulas. To add a formula to the text field, click the Add button.
- Functions
Lists all functions which can be used in the formula editor dialog box. To add a function to the text field, select a formula from the list.
A list with all predefined functions can be found in Functions in Formulas. This chapter also explains how to add user defined functions.
- Channel
This field displays a list with channel names. To add a channel to the text field, select a name from the list.
The list displays global attributes and constant values as well.
- Operators
- The operators +, -, *, / can be used in a formula. Click the operator button to add the operator to the text field.
- Formula Text Field
Specify the formula in this text field. A formula has the following structure:
NewChannel = Expression
The formula starts with the channel name followed by the assignment Operator = followed by the formula expression. You can use blank characters anywhere between operators, identifiers, and constants.
A channel name that already exists in the NC file will be overwritten.
Go to the Defining Formulas chapter for more information about writing formulas.
- Calculate formula only if
- You can specify conditions to decide if a formula should be calculated or not, e.g diesel, turbo etc. If the condition is not true, the formula will not be calculated. See Definition of a Condition.
- Handle Missing Values
- This option should normally be checked. If you would like to handle missing values in the formula yourself, clear this option.
- Unit
- Specify the channel unit.
- Decimal Places
- Specify the number of decimal places for the new channel.
- Description
- The description is displayed in the formula list, see toolsformula-list
- Comment
- Here you can type a comment
- Register Formula
If the option is not selected, the formula will only be evaluated once. The formula will be saved in the NC file. To edit the formula, right click on the formula channel in the data grid and select Add Formula Channel.
When this option is marked, the formula will be registered and evaluated every time F9 is pressed.
The formula is saved as an IC file in the formula directory. The file name is the name of the formula channel with the prefix _fi_ and the file name extension .ic, e.g. _fi_Power.ic.
The formula is saved in the directory that is specified in the Formula Configuration dialog box.
- OK
- When OK is clicked, the formula is checked and evaluated. If the formula contains a syntax error or unknown channel names, an error message is generated. In this case fix the problem and click OK again.
Defining Formulas¶
The formula can contain the following elements:
Parentheses (). The number of parentheses levels is not limited.
The +, -, *, /, ** operators are supported. The power operator can be used instead of **. The character ^ can be used as a power operator. Attention: Instead of ** and ^ it is recommended to use the pow() function, because it handles missing values. (see Functions in Formulas).
Numbers of the following form; 1.23, 1e12, -13. Only the period (.) is allowed as the decimal character (no comma).
Names of measured channels or other formula channels. The name must begin with an alphabetic character an underscore (‘_’), followed by zero or more alphanumeric characters including the underscore. Case is significant.
Function calls, for example abs() (see Functions in Formulas).
The string length of a formula is limited to 255 characters including blank characters.
A formula can be broken up in sections. Each section should be written in one line and must end with a semi-colon (;). The semi-colon can be used to split a long formula. Except for the last line, each line must contain a = character. The sum of all characters is again limited to 255. Example:
A * 9550; A = n * m;
Constants can be used inside a formula. The constants should be defined in the constant table (see The Constant Table).
Valid formulas are e.g.:
B_20 * Rho_20 * 1000 / P_EWG c_Anteil / 100
while the following formulas are invalid:
(n_Motor * Md_Motor) / 9550,0
The decimal separator is the point. The number 9550,0 is not permitted.
100 * B_20 / V-ACT
The character "-" in the channel name is not permitted.
Functions in Formulas¶
Formulas specified in an Excel table can contain function calls such as sqrt( 98.15 / (T_Intake + 273.15) ) which calculates the square root of 98.15 / (T_Intake + 273.15).
Here is a list of the specified functions:
abs(c)¶
Calculates the absolute value of c.
atan(c)¶
Calculates the arcus tangents of c.
log(c)¶
log calculates the natural logarithm of c.
log10(c)¶
calculates the base-10 logarithm of c.
cos(c)¶
Calculates the cosinus of c.
tan(c)¶
Calculates the tangents of c.
counter()¶
Creates the numbers 1,2,3,...
exp(c)¶
Calculates e^c.
int(c)¶
Cuts off the decimal places of c.
get_val_at(c, i)¶
Ruturns the value of at the position i of channel c. i = 1 returns the first element. i = -1 retuns the last element. i = -2 retuns the second last element.
Example: SZ2 = get_val_at(SZ, -1)
len(c)¶
Returns the number of elements in channel c. Example: mean = sum(c)/len(c).
max(c)¶
Returns the maximum value of channel c.
max(c1, c2)¶
Returns a channel which is r[i] = max(c1[i], c2[i]).
max(c1, r)¶
Returns a channel which is r[i] = max(c1[i], r).
min(c)¶
See max(c)
min(c1, c2)¶
See max(c1, c2)
min(c1, r)¶
See max(c1, r)
mean(c)¶
Returns the average value of channel c.
pow(c, n)¶
Calculates c^n.
rand()¶
Creates random numbers in the range 0.0 to 1.0. Example: r = srand(99) * rand().
replace_missings(c1, c2)¶
Replaces “Missing Values” of channel c1 with the corresponding value of channel c2. To use this function, the option Handle Missing Values must be cleared (see The Add Formula Channel Dialog Box).
replace_missings(c1, value)¶
Replaces “Missing Values” of channel c1 with the value value.
sin(c)¶
Calculates the sinus of c.
sqrt(c)¶
Calculates the square root of c. If the channel contains data smaller than 0, missing values will replace them.
srand(r)¶
Sets the random number generator to a specified value .
sum(c)¶
Returns the sum of the elements of channel c.
cumsum(c)¶
Returns the cumulative sum of the elements of channel c.
if_than_else(expr, than_exp, else_exp)¶
Depending on expr, the function returns than_exp or else_exp. The parameters can be scalar values or vectors. Vectors must have the same length. Example: be2 = if_than_else(compare_less(torque, 3), 500, be).
compare_less(c1, c2)¶
c1 is less than c2. Is used mainly in conjunction with the if_than_else function.
compare_lessequal(c1, c2)¶
c1 is less than or equal to c2. Is used mainly in conjunction with the if_than_else function.
compare_notequal(c1, c2)¶
c1 is not equal to c2. Is used mainly in conjunction with the if_than_else function.
compare_equal(c1, c2)¶
c1 is equal to c2. Is used mainly in conjunction with the if_than_else function.
compare_greater(c1, c2)¶
c1 is greater than c2. Is used mainly in conjunction with the if_than_else function.
compare_greaterequal(c1, c2)¶
c1 is greater or equal to c2. Is used mainly in conjunction with the if_than_else function.
and(c1, c2)¶
Boolean AND operator. Is used mainly in conjunction with the if_than_else function.
or(c1, c2)¶
Boolean OR operator. Is used mainly in conjunction with the if_than_else function.
not(c)¶
Boolean NOT operator. Is used mainly in conjunction with the if_than_else function.
between(c, lower, upper)¶
c greater or equal lower and c smaller or equal upper. Is used mainly in conjunction with the if_than_else function.
PT1(rvT, rvY, T_const)¶
PT1 element: z = (y - max) * (1 - exp("t-1" - t / T)) + "Z-1".
smooth(c, width)¶
Running average. Width is half of the window width in number of data points. The function is using moving_average. Example: NOx = smooth(NOx, 50)
smooth_time(c, TimeChannel, TimeWindow)¶
Running average. TimeWindow is half of the window width in the units of the given TimeChannel. Example: Nox_s = smooth_time(NOx, time, 1.7)
smooth_median(c, nNeighbor)¶
Running median. nNeighbor is the window size of the moving window in the range 3 to 1025. Even numbers will be rounded up to the next odd number. For each window the middle value found is used. The filter can be used to reduce random noise and spikes. (see moving_median).
Example: ATL_speed_s = smooth_median(ATL_speed, 5)
5 consecutive points are sorted ascending and the third point is used. For a window size of 5, the first 2 point and the last 2 points are not altered.
given: ATL_speed = [5, 7, 6, 4, 27, 8, 4, 5]
result: ATL_speed_s = [5, 7, 6, 7, 6, 8, 4, 5]
bit(c, nBit)¶
Returns the Bit n of c. nBit starts with 1.
derivative(x, y)¶
Calculates the derivative.
integral(x, y)¶
Calculates the integral.
exclude(c, minval, maxval)¶
Sets all values of c in the range minval to maxval to missing_value.
The User Defined Functions chapter describes how user functions are defined.
Channels with Missing Values¶
The formula interpreter can handle missing values.
In the following figure, channel EngSpd 6th measurement does not contain a valid value. Instead the word "Missing" is displayed.
Because the channel P=f(EngSpd, SAETrq) is dependant on EngSpd and the resulting channel P displays "Missing" in record 6.
MISSING_FLOAT = 1e10
Formula Import from an Excel Workbook¶
New formulas can be specified by adding the formula to an Excel Sheet. An example file can be found in the directory UniPlot\formula. The file name is formula.xls. This file should only be used as a template. It will be overwritten the next time you install an UniPlot update. Just open the file and save it under a new name in the same directory.
To import an Excel Workbook with a formula sheet, choose Tools=>Import Formulas from Excel File.
The table contains 8 columns. The columns have the following meaning:
- Column - FunctionName The formula name.
- Column - Description A brief description.
- Column - Unit The formula unit. The formula interpreter does not support any unit conversions. The formula has to be defined to use the correct units.
- Column - ChannelName Name of the channel in the NC file.
- Column - Formula The formula. Example: (speed * torque) / 9549.3.
- Column - OnlyIf Name of a condition.
- Column - Numberformat Format description, e.g. %g or %lf.
- Column - Comment This column can contain a comment.
The first cell (A1) in the Excel table must contain the key word “UniPlotFormulaTable” or “UniPlotFormelTabelle”.
The second row contains the column names.
More details about formulas can be found in chapter Formula Interpreter 2 - Creating a formula table.
id-202804