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).
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.
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 dialog, then proceed as above.
To save the function you’re editing, click OK.
To delete existing functions, select them in the 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¶
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. You can drag in as many inputs as you like to an Operation.
Addition, Subtraction, Multiplication, Division, Modulus and Power are all arithmetic operations. Note that Modulus only works with whole numbers as inputs.
Minimum, Maximum and Average take the minimum or maximum or average of all their inputs. (If some inputs to a Minimum, Maximum or Average are null, those null inputs will be ignored.)
Coalesce works the same as SQL’s COALESCE operator: if the first input is not null, it will return that first input. If the first input is null, it will look at the second input. It will keep looking along its inputs until it finds one that is not null. If all are null, it returns null.
Any True and All True are logical operations. They expect inputs of type Yes/No, and you should set their output type to Yes/No.
For some operations the behaviour with more than two inputs is obvious; for others, less so, and you should experiment to confirm that you understand it.
Bitwise / Logical Operation¶
These are similar to Operation elements, but carry out bitwise operations. 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 “Whole Number”. They differ from Any True and All True in that Bitwise / Logical Operations work on all bits of a whole number, rather than just on a yes/no basis. For example, 1010 AND 1001 = 1000; 1010 OR 1001 = 1011; etc.
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:
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. If multiple ranges match the input, the first matched range will be used, so if your ranges are 1 to 5 and 2 to 6, only inputs of greater than 5 will match the second range.
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.
If the Result Field you select has a Display Type different from its Field Type, then you can set the Return Type to be either the Functional Value or the Display Value. The Display Value is usually human-friendly text, whereas the Functional Value is the underlying numeric key value, which may be useful for feeding into subsequent function elements for comparisons, etc.
You can set an Asset Input, if the result table you have selected has Asset or Component_ID as a key field (for example, if your Result Field is an Asset Information field). Only use this for Asset or Component_ID — for any other table’s key field, add a Filter, as shown below. An Asset Input must have a type of Whole number (not Numeric).
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 various “closest” filters (“closest (either)”, “closest (lower or equal)”, “closest (higher or equal)”, “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.
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. (Be aware that using an Aggregate of Max or Min is usually faster than using a filter for highest or lowest.)
“contains” lets you search for a substring within an alphanumeric input. You can use “_” and “%” as wildcard characters, with “_” matching any single character and “%” matching several characters, so “abcde” contains “a_c”, and also contains “a%d”.
All filters must be matched for results to be returned; in other words, filters are implicitly connected by ANDs.
Lookups may be executed a large number of times, so it may be worth configuring them so that NEXUS can best optimise their execution. Aggregates such as “Max” are more efficient than Filters such as “highest”. In Filters comparisons, “=” is better able to be optimised than <, >, <=, >=. Results are cached, so the first lookup in a particular circumstance may be slower than subsequent lookups. For small frequently-used tables ( a few hundred rows), all the rows in the table will typically quickly get cached, and will remain cached for the entire run of the application. If the value changes, cache entries are expired as appropriate, then re-cached the next time they are requested by a function etc.
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! An 0!”, 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 Template Axis Type 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) = 14 INSTR(‘CORPORATE FLOOR’,’OR’, 1) = 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. | GETDATE( ) = <Today’s current date> |
| GetDateTime | Returns the current system date and time. | GETDATE( ) = <Today’s current date and time> |
| IsNull | ISNULL(A, B) returns A if A is not null; or B if A is null. See below for details. | ISNULL(<null>, 10) = 10 ISNULL(<30>,10) = 30 |
| LastInspectionDate | Returns the last inspection date for a component. | N/A |
| Linear Interpolation | Specify Ymin, Ymax, Xmin and Xmax, and for a given Xset, this function will return Yset. | LINEAR INTERPOLATION(0,0, 2,4, 1) = 2 |
| 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 |
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. Note that an alphanumeric field that contains an empty string is not null – to set the field value back to null, click the “X” button at the right of the field.
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.)
Tests¶
You can write test cases for your functions, under the “Tests” tab. Test cases let you test a function as you create it, and storing your tests within the function lets you verify that a function still does what it did when you created it, and let you re-validate a function after changes. When writing tests, you should write at least one that returns a valid result, and if it’s possible for your function to return an Error, you should write at least one test for each possible error case.
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.