Functions

Configuration ‣ General ‣ Functions allows you to create, edit and delete functions.

The Functions window enables you to build and edit customised functions which can be used in other areas of NEXUS IC, such as Asset Information fields, Event fields and Report Sources. You can drag and drop elements into the Function Editor, then connect the elements together to define the way in which data flows through your function.

Functions are integral to NEXUS IC. Functions are used within Risk Models (defining models, matrices and parameters), they are also used in Asset Information fields (e.g. corrosion rates, retirement dates, pressures, wall thicknesses etc) and Event Definitions (e.g. functions to calculate remaining wall thickness or span lengths).

_images/functions.png

Add

To add a new function, click the Add button at the top of the “Configuration - Functions” dialog. Give your new function a name and (optionally) a category. In the bottom half of the dialog, click the ‘+’ next to Elements, and drag a Function Parameter from the Elements tree to the design area at the right. (All functions are required to have at least one function parameter.) Drag other elements as desired.

_images/functions.add.png

Once elements are in the design are at the right, you can connect two elements by dragging from the output square at the bottom of one element to a second element. Your drag must begin on the source element’s output square, but can end anywhere in the target element (not just on its input squares).

You can replace an existing connection by dragging from an output square to the specific input square whose connection you want to replace. You can break an existing connection by dragging it off an input square and dropping it on a blank part of the design area.

You can connect one output to multiple inputs — there is no limit to the number of places you can connect a single output to.

To view “on the fly” values for your function, click the Show Results button. You can also enter Input Values at the bottom of the Tests tab. The function will be evaluated using the input values you specify.

If you give an element an input of a type it is not expecting, instead of a green result you will see a yellow error message at the bottom of that element, explaining the type mismatch. You will similarly get yellow error messages for other error cases, such as division by zero. These errors are only visible if the Show Results button is selected.

To edit an existing function, click the Edit button at the top of the Configuration ‣ Functions dialog, then proceed as above.

To save the function you’re editing, click OK.

To delete existing functions, select them in the Configuration ‣ Functions dialog and click the Delete button at the top of the dialog.

To see if a function is being used elsewhere in the application, click Connections.

Functions and function elements in NEXUS IC 6 are unit aware: if you have a function with two inputs leading to an Addition operation, and one function has units in metres while the other has units in millimetres, NEXUS IC will correctly deduce that one number needs to be scaled by a factor of 1000 before the two numbers are added. (Which direction the scaling happens depends on the output unit you select for the Addition element.) For many function elements, you can select the output unit. (Note that NEXUS IC isn’t dimensionally aware: if you divide a length by a time, it won’t understand that the result is a velocity.)

Function Elements

_images/functions.1.png

Function Parameter

A function parameter is an input to the function. For example, in a function that calculates the circumference of a circle given a radius value, you can add a Function Parameter element, that provides the ability to enter a value for the radius. This value is then multiplied by 2 and by the value of pi to calculate the circumference of the circle. When defining a Function Parameter, you need to give it a name and a data type. Function Parameters may be alphanumeric, whole numbers, real numbers, boolean values (true or false), dates, times, or combined date/time values.

If you tick “Allow Null Inputs”, you can specify a Default Value to be used when the input is null.

Constant

Constant functions elements are used when a data value is known and will remain the same for every situation where the function is run. When defining a Constant, you need to supply a name for the constant, the value of the Constant and the field type. Constants (like Input function elements) can be alphanumeric, numbers, Boolean values (true or false), or date/time values.

Operation

Operation function elements provide data manipulation functions. Operators take input data from various sources such as Input, Constant or Decision elements, or even other system or user-defined functions. The Operation element can be configured for addition, subtraction, multiplication, division, modulo, power, minimum, maximum, or average. (Those last three options are not aggregates, in the sense used by the Lookup element — rather, they simply take the minimum or maximum or average of all their inputs. If some inputs to a minimum, maximum or average are null, those inputs will be ignored.) You can drag in as many inputs as you like to an operation. For some operations (addition, multiplication, minimum, maximum, average), the behaviour with more than two inputs is obvious; for others, less so, and you should experiment to confirm that you understand it. Note also that Modulo only works with whole numbers as inputs.

Bitwise / Logical Operation

These are similar to Operation elements, but expect Boolean (yes/no) inputs. Bitwise / Logical Operation elements can be configured for And, Or, Xor (eXclusive Or), or Not. You should set the Result Type of a Bitwise / Logical Operation to “Yes / No”.

Concatenate

These are similar to Operation elements, but are designed to concatenate several inputs together (converting them to Alphanumeric if necessary) and give an Alphanumeric as an output. You should set the Result Type of a Concatenate element to “Alphanumeric”.

The Format property can be used to control how values are converted to strings, and how the final concatenated string appears. (Programmers may find this similar to the concept of printf format strings in C.) If the input is a whole number, you can put %d in the format string at the point where you’d like that whole number to appear. If the input is a numeric, you can put %f. You can put other text in the string literally as desired, and to get a % symbol, put %%. So a format string like “There are %d apples, which fill %f%% of the basket” would result in output like “There are 1 apples, which fill 12.34% of the basket”. If your input types don’t match the format string you’ve specified, you’ll get an error message. So in this example we’ve assumed that the first input is a whole number. If it was in fact a numeric, you’d see an error like “Format is invalid for for the inputs.”

You can put a number between the “%” and the letter to specify the width. If the number turns out to be less characters than the width you’ve specified, it will be padded with spaces. You can put a ”.” after that width (or just directly after the “%”) followed by a precision, to specify the number of decimal places for a numeric. So “%2d” might result in output like ” 1”; “%.3f” might result in output like “12.340”.

You can use types other than “d” for Whole Number and “f” for Numeric; here’s a list:

Type Output
d Decimal. Input must be a Whole Number.
u Unsigned decimal. If input is negative, it will be shown as positive. Input must be a Whole Number.
e Scientific: you will get output like “1.234E1”.
f Fixed: you will get output like “12.34”.
g General: you will get fixed or scientific output, whichever is shorter.
n Number: you will get a number with thousand separators, like “123,456.78”.
m Money: you will get a currency output, formatted as specified by your settings in Windows control panel.
s String. If one of your inputs is a string, you can use “%s” to put it in the format string: “There are %d %s, which fill %f%% of the %s”. If you specify a precision, like “%.3s”, the string will be limited to at most that many characters — any remainder will be truncated.
x Hexadecimal. Input must be a Whole Number.

Decision

Decision function elements in the NEXUS IC database are explained below:

_images/functions.2.png
Case

Evaluates a list of conditions and returns one of multiple possible result expressions. If the Case input does not equal any of the defined conditions, then the Default is returned.

Compare

Compares two inputs (comparators) and returns one of two values depending on whether the inputs match. Comparisons available in the Compare decision include: Equals (=), Not equals (<>), Greater than (>), Less than (<), Greater Than or Equal (>=), Less Than or Equal (<=).

Matrix

Evaluates a number of inputs and returns the looked-up value. You can add more inputs with the Add Column Input and Add Row Input buttons. If you have several column inputs or several row inputs, they must all be matched for that cell to be picked. That effectively means that this is an n dimensional matrix. The 2-dimensional case (with one column input and one row input) is the simplest and most common, but if your situation demands more dimensions, add inputs to suit.

When no cells are matched, the Default Value will be used. You should ensure that the result type of the Default Value is the same as the result type of the Matrix.

Range

The Range element is similar to the Case element, except that you specify a range of input values for each case, rather than a single specific value. Range evaluates a numeric input against a series of numeric ranges and returns the found value. For each range, you specify the Lower and Upper as numeric values, and then choose a Result from the available inputs. A Range element needs at least three inputs: one to supply the Case value that will be used to decide which range is matched (if any); one for the Default Value which will be used if no range is matched, and one to define a result for the first range. If you want more than one range, add more than three inputs. If you want to re-use one input several times, drag that input onto the Range element several times.

_images/functions.3.png

Lookup

Returns a summarised value from various sources of data within the NEXUS IC database.

So if you wanted to (say) fetch an Asset Information field from an Asset, you could choose that Asset Information field as the Result Field, and connect the Asset Input to a Function Parameter which will be fed from Asset. Almost any field from almost any table can be used as the Result Field.

You can also aggregate data from the Result Field by selecting an Aggregate: Max. Min, Average, Sum, Standard Deviation or Count. If you select an aggregate, NEXUS IC will make a list of all the results and aggregate as appropriate. For example, if you chose a field from an event form as your Result Field and Min as your Aggregate, then NEXUS IC will look through all the events on that asset, and return the minimum value from that field in that list of events.

You can set an Asset Filter. The default, “No Children”, returns results from just the single asset specified by the Asset Input. “This Asset and dependent Assets” returns results from the asset specified, and also from that asset’s children, grandchildren, great-grandchildren, etc. “Dependant Assets but not this Asset” does almost the same thing, but leaves out results for the asset specified. “Immediate Children” returns results from the specified asset’s immediate descendants, but not from the asset itself, nor from any grandchildren, great-grandchildren, etc. “Parent Assets” looks up the tree instead of down, returning results from the specified asset’s parent, grandparent, great-grandparent, etc., all the way to the root of the asset tree. (If you are using an option other than “No Children”, you will typically also want to specify an Aggregate.)

If an asset appears in multiple Asset Views, it may have different parents and different descendants in different views. These asset filters will match parents and descendants in all asset views.

You can also specify a Workpack Filter, whose options (Most Recent, All, Specific Workpack) are reasonably self-explanatory.

Filters can be used to filter the list of results that would otherwise be returned to a shorter list (possibly containing exactly one item, thus avoiding the requirement to use an Aggregate). You can drag extra inputs onto the Lookup element for use as Filter inputs. The first six comparisons (=, <>, >, >=, <, <=) are straightforward. The next three (“closest (either)”, “closest (lower)” and “closest (higher)”) are special. Suppose you want to find the event whose KP is closest to a particular value: for this you would use “closest (either)”. Or suppose you wanted to find the event just before this one; i.e. the event with KP closest to a particular value, but lower: for this you would use “closest (lower)”. And similarly, “closest (higher)” would be used to find the next event after a particular KP. If there were an event at the particular KP you were filtering on, you would want to add another filter saying “KP <> the KP input”, to exclude that event. For “highest” and “lowest” you need specify no input; these simply return the single result that has the highest or lowest value in whatever Field you specified in the filter.

All filters must be matched for results to be returned; in other words, filters are implicitly connected by ANDs.

Notes

Notes are used when building functions for reference and documentation purposes. Notes are placed in the Function Builder work space. You should use Notes whenever you think a function is not self-explanatory, where you want to refer to a standard, document changes to a function, etc.

Risk

Returns the aggregate risk value for an asset and all its children in a particular asset view.

Error

In version 6, the function builder includes the concept of errors. You can see errors by, for example, dividing by zero or by feeding an element an input of a type it did not expect.

But you can also deliberately include errors. For example, suppose you have a function whose input must not be 0. You can add a comparison which compares that input to 0, and if true, returns the value of an Error element. If you set the Error value inside the Error element to “Oh no! A zero!”, then when the function has its input set to 0, the user will see that error message output.

The advantage of using an Error element is that it can give a textual description to the user explaining what is wrong without changing the output type of the function — the output of the function might still be of type Numeric. This means that if this function’s output is in turn consumed by other functions, those functions will get a Numeric value as they expected. In this way, functions can chain to other functions, while also giving descriptive messages to the user.

Is Anomalous

You can use this element to check, within a function, if a particular event field causes any Anomaly Triggers to fire. Its input should be an event Header_ID.

Solver

The solver element is used within charts to solve for a particular input parameter of a function — see Chart Templates for details.

Function

You can embed an entire other function into this function via the Function element. This is the same as dragging in a System Function or User Function — see below.

System Functions

System function elements in the NEXUS IC database can be broken up into Character functions, mathematical functions and other functions. These system functions are pre- defined and explained below:

Character/String Functions
Function Description Example of use
ASCII Returns the ASCII code value of the leftmost character of a character expression. ASCII(‘Alphabet’) = 65
CHR Converts an ASCII code to a character. CHR(65) = ‘A’
INSTR Returns the starting position of the specified expression in a character string.

INSTR(‘CORPORATE FLOOR’,’OR’, 3, 2) = 14

INSTR(‘CORPORATE FLOOR’,’OR’, -3, 2) = 2

LEN Returns the number of characters of the given string expression, excluding trailing blanks. LEN(‘Alphabet’) = 8
LOWER Returns a character expression after converting uppercase character data to lowercase. LOWER(‘Alphabet’) = ‘alphabet’
LTRIM Returns a character expression after removing leading blanks. LTRIM(‘ Alphabet’) = ‘Alphabet’
REPLACE Replaces all occurrences of the second given string expression in the first string expression with a third expression. REPLACE(‘Alphabet’,’ph’,’f’) = ‘Alfabet’
RTRIM Returns a character string after truncating all trailing blanks. RTRIM(‘Alphabet ‘) = ‘Alphabet’
SUBSTR Returns a part of a character expression. SUBSTRING (‘Alphabet’,0,6) = ‘Alpha’
UPPER Returns a character expression with lowercase character data converted to uppercase. UPPER(‘Alphabet’) = ‘ALPHABET’
Mathematical Functions
Function Description Example of use
Abs Returns the absolute, positive value of the given numeric expression. ABS(- 15) = 15
ACos Returns the angle, in radians, whose cosine is the given numeric expression; also called arccosine. ACOS(.3) = 1.26610367
ASin Returns the angle, in radians, whose sine is the given numeric expression; also called arcsine. ASIN(.3) = .304692654
ATan Returns the angle in radians whose tangent is the given numeric expression; also called arctangent. ATAN(.3)= .291456794
Ceil Returns the smallest integer greater than, or equal to, the given numeric expression. CEIL(15.7) = 16
Cos Returns the trigonometric cosine of the given angle (in radians). COS(180 * 3.14159265359/180) = -1
Erf Gaussian Error function. See https://en.wikipedia.org/wiki/Error_function Erf(0) = 0
Exp Returns the exponential value of the given numeric expression. EXP(4) = 54.59815
Floor Returns the largest integer less than or equal to the given numeric expression. FLOOR(15.7) = 15
Ln Returns the natural logarithm of the given numeric expression. LN(95) = 4.55387689
Log Returns the base- 10 logarithm of the given numeric expression. LOG(10,100) = 2
Round Returns a numeric expression, rounded to the nearest whole number. ROUND(15.193) = 15
RoundTo Returns a numeric expression, rounded to the specified length or precision. ROUNDTo(15.193,1) = 15.2 ROUNDTo(15.193,-1) = 20
Sign Returns the positive (+1), zero (0), or negative (- 1) sign of the given expression. SIGN(- 15) = - 1
Sin Returns the trigonometric sine of the given angle (in radians). SIN(30 * 3.14159265359/180) = .5
SqRt Returns the square of the given expression. SQRT(26) = 5.09901951
Tan Returns the tangent of the input expression. TAN(135 * 3.14159265359/180) = -1
Trunc Returns n truncated to a whole number. TRUNC(15.79) = 15.7
TruncTo Returns n truncated to m decimal places. m can be negative to truncate (make zero) m digits left of the decimal point. TRUNCTo(15.79,1) = 15.7 TRUNCTo(15.79,-1) = 10
Compare Functions

There are a variety of Compare functions (“Compare A = B”, “Compare A < B”, “Compare (A = B and C = D) or (E in (F, G, H) and I = J)”, etc.) They all compare the various inputs in the way described in the function name.

Other Functions
Function Description Example of use
Day Returns the Day part of a date. DAY(38462) = 22
GetDate Returns the current system date and time in the database server standard internal format for datetime values. GETDATE( ) = <Today’s current date>  
IsNull The syntax for this function is ISNULL(check_expression, replacement_value), where check_expression is the expression to be checked, and replacement_value is the expression to be returned if check_expression is NULL. check_expression can be of any type. replacement_value must have the same type as check_expression. ISNULL(<null >, 10) = 10 ISNULL(<30>,10) = 30
LastInspectionDate Returns the last inspection date for a component. N/A
Length Calculates length from two parameters, i.e. ABS(Param2 - Param1) LENGTH(5.418 – 6.254) = 0.836
Month Returns the Month part of a date. MONTH(38462) = 4
NextInspectionDate Returns the next inspection date for a component. N/A
PassThru Returns parameter value without any modification. PASSTHRU(‘Alphabet’) = ‘Alphabet’ PASSTHRU(123) = 123
ToDate Converts the input value to date data type. TODATE(38462) = 2005-04-22 TODATE(‘22 April 2005’) = 2005-04-22
ToNumeric Converts the input to a numeric data type. TONUMERIC(‘123’) = 123 TONUMERIC(TODATE(‘22 April 2005’)) = 38462
Year Returns the Year part of a date. YEAR(38462) = 2005

User Functions

User functions are functions that have been defined by the Users. They can be further categorised by type.

Nulls

Almost any calculation involving a null will return null. For example, 2 + null = null.

Any comparison involving a null will always return false. This is occasionally a bit subtle: in a Comparison object, if you compare null to null, it will return whatever value you have set for the False case.

(This is in line with accepted IT industry practice for nulls in data.)

There are some exceptions, where the right thing is to produce a numeric value despite the presence of some nulls: if you use an operation object to calculate a Minimum, Maximum, or Average, nulls will be left out and the non-null values will be used to calculate the answer. For example, the Average of 1 and null is 1. (If all inputs are null, a null will of course be returned: the average of null and null is null.)

Load / Save Template

Clicking Save Template will save the selected function as a file. This function can then be loaded into this or another database via Load Template.