Catalogue of Metadata, Syntax and Functions

This catalogue details each of the items in the pinnable Insert list for Calculations and Filters. Each item includes an intentionally trivial example to illustrate the use of the item, along with an explanation of the effect of the expression.

Existing Items

This section covers the items listed in the left-hand side of the pinnable Insert list:

To pin these lists to the Calculations tab, enable the Pin Window option:

Metadata

This metadata item is available for imported points objects. It is the row ID from the points table.

Example

Explanation

The filter even rows will select for points with a row [id] that has no remainder when divided by 2.

x, y and z

These three metadata items are the variables for locating each point in a points object in X, Y and Z coordinates. Select an item to add it to the expression at the insertion point. Note that whenever one of these metadata items is added to an expression, it is wrapped in square brackets. This is not available for block objects; use xc, xy and xz instead.

Example

Explanation

The numeric calculation YX will be assigned the value of the location of [y] multiplied by the location of [x].

xc, yc and zc

These three metadata items are the variables for locating the centroid of each block, in X, Y and Z coordinates. Select an item to add it to the expression at the insertion point. Note that whenever one of these metadata items is added to an expression, it is wrapped in square brackets. This is not available for points objects; use x, y and z instead.

Example

Explanation

The numeric calculation top will be assigned the value of the location of [zc] the altitude of each block centroid from the zero reference, plus half the height of the block.

dx, dy and dz

These three metadata items are the variables for the block dimensions in X, Y and Z coordinates. Select an item to add it to the expression at the insertion point. Note that whenever one of these metadata items is added to an expression, it is wrapped in square brackets. This is not available for points objects.

Example

Explanation

The numeric calculation surface area will be calculated by figuring the area of each face of the block by multiplying the X and Y dimensions, X and Z dimensions and Y and Z dimensions and adding them together.

volume

This metadata item provides the volume for each block. Note that when this metadata item is added to an expression, it is wrapped in square brackets. This is not available for points objects.

Example

Explanation

The numeric calculation density will be assigned the value of the variable [mass] divided by the metadata item [volume].

xi, yi and zi

These three metadata items are the variables for locating each block by X, Y and Z index. Select an item to add it to the expression at the insertion point. Note that whenever one of these metadata items is added to an expression, it is wrapped in square brackets. This is not available for points objects.

Example

Explanation

The numeric calculation remaining will be assigned the value of the block's AU_gpt evaluation, unless [zi] the Z index of the block is greater than or equal to 40, in which case the block status will be set to the invalid value outside.

Evaluations

Each of these items are automatically added to the list whenever an evaluation is added to the object. When added to an expression, the item represents a placeholder in the calculation for an estimated value, as the expression is evaluated for each of the locations in turn.

Note you can expand each evaluation in the list to see the attributes for the estimation evaluation that may also be selected instead of or in addition to the estimated value.

Example

Explanation

The numeric calculation halved is defined by the evaluation [AU_gpt] divided by 2. Each location in the object will have its own value for AU_gpt, and this calculation uses those values to create a new value named halvedfor each location, using the formula above.

Variables, Calculations and Filters

Each time you create a new variable, numeric calculation, category calculation, or filter in Calculations, it will also be added to the Existing items list. You can select them from this list and they will be inserted into your new expression at the insertion point. Note that whenever one of these named items is added to an expression, it is wrapped in square brackets.

Example

Explanation

This example is only attempting to illustrate how variables, calculations and filters that have already been defined can be referenced by name in new calculations; the calculation highlight is not intended to be useful.

It is good practice to break your calculations down into parts, giving each part a relevant and readily identifiable, unambiguous and easily understood name. This will make your calculations more readable and clear. Using Variables to define a constant with a name makes it easy to understand the utility of that particular constant when you use it in a calculation. You may also be able to re-use certain parts such as filters or constant variables, so you do not need to define the same thing repeatedly.

Be careful not to inadvertently name something incorrectly, such as naming a volume as "area", as this could give rise to difficult-to-locate errors in your calculation.

Syntax and Functions

This section covers the items listed in the right-hand side of the pinnable Insert list.

To pin these lists to the Calculations tab, enable the Pin Window option:

Statements

(…) Brackets

Brackets are used to enclose an expression so the operations on the values within the brackets take precedence over operations outside the brackets.

Example

Explanation

1+2 will be calculated prior to calculating the result of the expression, following the standard order of mathematical operations.

if(::) If block

The If block is used for conditional logic. This allows multiple pathways to results depending on selected conditions, or categorisation based on values.

An If block will be evaluated by each test → result, row by row, separately and in order downwards by row. Each test has an output that can be ‘true’, ‘false’, or an invalid value ‘error’, ‘blank’, ‘without_value’ or ‘outside’. The result output is produced by the execution of the result expression. The If block output follows these rules:

If a test output is ‘error’, the If block output is ‘error’ and no further processing of subsequent rows is done.
If a test output is ‘false’, the result expression is not executed, and the next row is considered.
If a test is ‘true’, the result expression is executed and the result output is used for the If block output and no further processing of subsequent rows is done.
If all the tests are ‘false’, the ‘otherwise’ result expression is executed and its output is used.
If a test output is an invalid value (without_value, blank, outside) the result expression is not executed and the test output’s invalid value is remembered. The subsequent rows are then run.
If a subsequent test output is ‘true’ after an earlier one produced an invalid value, the previous test output is discarded and the new row’s result expression output is used as the output for the If block.
If all test outputs are invalid status values, the highest priority status of all the remembered invalid statuses is used as the output result. The priority of non-error invalid status values is: outside > without_value > blank.

Additionally, it is possible to choose to produce invalid values as the output of result expressions.

Example

Explanation

Cu_pct is the name of an evaluation applied to all the points in a points object. As the if(::) If block calculation is run for each point, the evaluation for each point replaces this variable name in the expression. If the value is greater than the value of the constant pi, the result for that point will be the text string "Blue". Otherwise, if the value is less than or equal to pi, the result will be the string "Red".

Additional rows may be added. Each row follows on from the left-over results of the line before, simplifying the logical expression that may be used.

Explanation

Note the addition of the line [Cu_pct] > e → "Purple". This line can be interpreted to mean: if the value estimated for a point is less than or equal to pi, but greater than e the result shall be "Purple". The part about it being less than or equal to pi is implied because the line follows the previous line [Cu_pct] > pi → "Blue".

Note that expression elements before and after the if expression can be entered. This allows the if(::) If block to form part of a more complex or extensive expression.

Explanation

The earlier conditional classification has now been embedded within a concatenation function, forming the first part of a two-part string concatenation. The concatenation function is adding the text string "-ish" to whatever is produced by the if(::) If block. Thus, if the value of the block being evaluated is 1.2, the result of the colour categorisation calculation will be "Red-ish".

Basic Operators

+ Add

An arithmetic addition operation.

Example

Explanation

next is assigned the value of the current imported points row [id] plus 1.

- Subtract

An arithmetic subtraction operation.

Example

Explanation

prev is assigned the value of the current imported points row [id] minus 1.

* Multiply

An arithmetic multiplication operation. Note that implied multiplication, putting factors adjacent to one another, is not supported. The * operator must be explicitly used.

Example

Explanation

product is assigned the value of [x] times [scale].

/ Divide

An arithmetic division operation.

Example

Explanation

quotient is assigned the value of [numerator] divided by [denominator].

% Modulo

An arithmetic modulo operation. This is an integer division operation that returns the remainder instead of the integer quotient.

Example

Explanation

remainder is assigned the value of [numerator] modulo [denominator], or in other words, [numerator] is divided by [denominator] to produce an integer quotient , the number of times [denominator] goes into [numerator], and a remainder, which is the number returned by this modulo function.

^ Power

A mathematical exponentiation operation where a base is raised to the power of the exponent.

Example

Explanation

area is assigned the value of pi * [radius]² (because ^2 is interpreted as ‘to the power of the exponent 2’ or 'squared'). Because [radius] happened to be defined as equalling 2, the result of the expression pi * 2² is 12.56637..., as can be seen from the result at the end of the expression.

and Logical and

A logical and operation.

Example

Explanation

filter will be true if the point is classified in the 'Dacite' part of the geological model AND the [z] coordinate for the point is above 2800; it will be false if either of these conditions are not true.

or Logical or

A logical or operation.

Example

Explanation

Dacite and ED will be true if the point is classified in the 'Dacite' part of the geological model OR the point is classified in the 'Early Diorite' part of the geological model, but it will be false if neither of these conditions is true.

not Logical not

A logical not operation.

Example

Explanation

Not Dacite will be true if the point is classified in the geological model as anything other than 'Dacite'. The logical operator not inverts the logical expression that follows the operator.

= Equal

A logical equality operator.

Example

Explanation

Dacite will be true if the point is classified in the 'Dacite' part of the geological model, and will be false for all other values.

!= Not equal

A logical not-equal operator.

Example

Explanation

Not Dacite will be true if the point is classified in the geological model as anything other than 'Dacite', and will be false when it is 'Dacite'.

< Less than

A logical less-than operator.

Example

Explanation

density under 1 will be true when the variable [density] is less than 1, and false otherwise.

< Less or equal

A logical less-than-or-equals operator.

Example

Explanation

density le 1 will be true when the variable [density] is less than or equal to 1, and false otherwise.

< Greater than

A logical greater-than operator.

Example

Explanation

density over 1 will be true when the variable [density] is more than 1, and false otherwise.

< Greater or equal

A logical greater-than-or-equals operator.

Example

Explanation

density ge 1 will be true when the variable [density] is more than or equal to 1, and false otherwise.

Complex Comparisons

Lower < n < upper

A pair of comparisons, with a logical result to indicate if the tested value n is between the lower value provided and the upper value provided.

Example

Explanation

filter will be true when the point evaluation [AU_gpt] is between the values of 5 and 8 (but not equalling 5 or 8); it will be false otherwise.

Lower <= n < upper

A pair of comparisons, with a logical result to indicate if the tested value n is between the lower value provided and the upper value provided, or equal to the lower value.

Example

Explanation

filter will be true when the point evaluation [AU_gpt] is between the values of 5 and 8 (but not equalling 8); it will be false otherwise.

Lower < n <= upper

A pair of comparisons, with a logical result to indicate if the tested value n is between the lower value provided and the upper value provided, or equal to the upper value.

Example

Explanation

filter will be true when the point evaluation [AU_gpt] is between the values of 5 and 8 (but not equalling 5); it will be false otherwise.

Lower <= n <= upper

A pair of comparisons, with a logical result to indicate if the tested value n is between (or equal to either) the lower value provided and the upper value provided.

Example

Explanation

filter will be true when the point evaluation [AU_gpt] is greater than or equal to 5 and less than or equal to 8; it will be false otherwise.

x in {a,b,...}

A logical inclusion expression. This will return true if x matches any element of the set of listed items.

Example

Explanation

If [colour] is one of the items in the list within the curly brackets, filter will be true. If [colour] is anything else, filter will be false.

x not in {a,b,...}

A logical exclusion expression. This will return true if x fails to match any element of the set of listed items.

Example

Explanation

If [colour] is not one of the items in the list within the curly brackets, filter will be true. If [colour] matches any item in the list, filter will be false.

Invalid Values

Invalid values are different types of results for “numeric” categorisation calculations that need special non-numeric results for certain category results. These have special meanings of their own without having to resort to interpreting negative numbers and zero as having special meaning.

blank means having no value, the value in the imported file is blank or has non-numeric data

without_value is often used to mean the estimator cannot produce a value (specific to blocks)

outside is used to indicate the block is outside the boundary of the domain (specific to blocks)

error generates an error, and provides an ‘error’ status value for the affected block or point

error(‘message’) is similar to error but includes a custom message.

Multiple case example

Explanation

If the variable [area] is equal to 0, the point will be marked with the special value blank. If the variable [area] is less than 0, the point will be marked with the special value outside. If [area] is greater than 0 and the variable [result] is equal to 0, the point will be marked with the special value without_value. If [area] is greater than 0 and [result] is greater than 0, the point will be will be assigned the value of the variable [result]. If [area] is greater than 0 and [result] is less than 0, the point will be given the special value error and status with the message 'negative result'.

is_normal(a)

A function that tests a to see if it is a normal value or an invalid value. If a is normal, it returns true. If a is invalid, it returns false.

Example

Explanation

If [number] has a normal value, filter will be true for that block. If it produces an invalid value, filter will be false.

is_blank(a)

A function that tests a to see if it is a blank invalid value. If a is blank, it returns true. If a is normal or another invalid value, it returns false.

Example

Explanation

If [number] has a blank status, filter will be true for that block. If it produces any other invalid value or a normal value, filter will be false.

is_without_value(a)

A function that tests a to see if it is a without_value invalid value. If a is without_value, it returns true. If a is normal or another invalid value, it returns false.

Example

Explanation

If [number] has a without_value status, filter will be true for that block. If it produces any other invalid value or a normal value, filter will be false.

is_outside(a)

A function that tests a to see if it is an outside invalid value. If a is outside, it returns true. If a is normal or another invalid value, it returns false.

Example

Explanation

If [number] has an outside status, filter will be true for that block. If it produces any other invalid value or a normal value, filter will be false.

Mathematics

pi Constant

The constant pi is an existing item you do not need to define yourself. It is defined to 15 decimal places as 3.141592653589793.

Example

Explanation

area will be calculated as pi multiplied by the square of [radius]. Note that pi is not enclosed in square brackets like user-created variables and constants, as it is an internal constant.

e Constant

The constant e, the base of the natural logarithm, is an existing item you do not need to define yourself. It is defined to 15 decimal places as 2.718281828459045.

Example

Explanation

comp will be calculated as e to the power of ([rate] minus 1). Note that e is not enclosed in square brackets like user-created variables and constants, as it is an internal constant.

log(n) Base 10

The common logarithm, the logarithm with base 10, i.e. log₁₀(n) or lg(n). This function will calculate the common logarithm of the value provided as n.

Example

Explanation

scaled will be calculated as log₁₀ of [measure].

log(n, base)

The logarithm of a number n to the base base.

Example

Explanation

scaled will be calculated as log₂ of [measure].

ln(n) Natural log, base e

The natural logarithm, the logarithm with base e, i.e. log_e(n). This function will calculate the natural logarithm of the value provided as n.

Example

Explanation

scaled will be calculated as log_e of [measure].

exp(n) Natural exponent

The natural exponent. This function will provide the result of eⁿ.

Example

Explanation

em will be calculated as e [measure].

sqrt(n) Square root

The principle square root of the provided number n.

Example

Explanation

sqrtmwill be calculated as the square root of [measure].

abs(n) Absolute value

The absolute value of a number is it's value with the sign of the number disregarded. The absolute value of -42 is 42. The absolute value of 42 is also 42.

Example

Explanation

absm will be whatever [measure] is, but without its sign; it will always be positive as a result.

Limits and Rounding

min (n, m, ...)

Returns the lowest of all the values in the set provided.

Example

Explanation

low will be the lowest of the three values provided, the metadata items for the X, Y, and Z point coordinates.

max (n, m, ...)

Returns the highest of all the values in the set provided.

Example

Explanation

high will be the highest of the three values provided, the metadata items for the X, Y, and Z point coordinates.

clamp(n, lower)

This clamp function tests the value n against the threshold lower and if it is less than lower the result will be lower; otherwise the result will be n. The effect is to push all the values below the threshold up to the threshold.

Example

Explanation

The output for modified will range from 0.25 up to the maximum value of [AU_gpt].If [AU_gpt] is less than 0.25, the output will be 0.25 instead. Otherwise, the output will be [AU_gpt].

clamp(n, lower, upper)

This clamp function tests the value n against the threshold lower and if it is less than lower the result will be lower; it tests the value n against the threshold upper and if it is more than upper the result will be upper; otherwise the result will be n. The effect is to squish all the values into a box between the lower and upper thresholds.

Example

Explanation

The output for modified will range from 0.25 up to 8. If [AU_gpt] is less than 0.25, the output will be 0.25 instead. If [AU_gpt] is more than 8, the output will be 8 instead. Otherwise, the output will be [AU_gpt].

round(n)

This function rounds the input value n to the nearest whole number.

Example

Explanation

The variable negative will be given the value -13 as the nearest whole number to -12.6789 used as the input to the function. The variable positive will be given the value 13 as the nearest whole number to 12.6789 used as the input to the function.

round(n, dp)

This function rounds the input value n to the number of decimal places specified by dp, a positive integer.

Example

Explanation

The variable negative will be given the value -12.3457, the value of -12.3456789 rounded to 4 decimal places. The variable positive will be given the value 12.3457, the value of 12.3456789 rounded to 4 decimal places.

roundsf(n, sf)

This function rounds the input value n to the number of significant figures specified by sf, which must be a positive integer >= 1. Rounding to a given number of significant figures is often preferred in scientific applications over rounding to a given number of decimal places, as outputs can be rounded to the same amount of significance as the inputs.

Example

Explanation

The variable negative will be given the value -12.35, the value of -12.3456789 rounded to 4 significant figures. The variable positive will be given the value 12.35, the value of 12.3456789 rounded to 4 significant figures.

floor(n)

This function removes the fractional part of a real number n and returns the integer number below the real number n. This remains true when n is a negative number.

Example

Explanation

The variable negative will be given the value -13, the integer below -12.3456789. The variable positive will be given the value 12, the integer below 12.3456789.

ceiling(n)

This function removes the fractional part of a real number n and returns the integer number above the real number n. This remains true when n is a negative number.

Example

Explanation

The variable negative will be given the value -12, the integer above -12.3456789. The variable positive will be given the value 13, the integer above 12.3456789.

truncate(n)

This function simply removes the fractional part of a real number n and returns the integer number without the fractional part. This means that for positive real numbers, the result will be the integer less than the real number n, but for negative real numbers, the result will be the integer greater than the real number n.

Example

Explanation

The variable negative will be given the value -12, the integer part of -12.3456789. The variable positive will be given the value 12, the integer part of 12.3456789.

Text

'abc' Text value

Use this item to add a text sequence to an expression. Selecting the item will add two single quotation marks with the cursor between, ready for the text sequence to be typed. You can of course simply type the quote marks into the expression yourself. Double quotations marks also work identically to the single quotation marks used by this item. If you need to include a quote mark inside your text sequence, you need to "escape" the character so it is not interpreted as the end of the text sequence, by entering two quotation marks for each quotation mark you want inside the text sequence. Alternatively, you can use a different type of quotation mark as the sequence wrappers; for instance to write Seequent's Region with an internal apostrophe, you might wrap the sequence with double quotation marks: "Seequent's Region".

Example

Explanation

The text sequence Seequent's Region (note: without the wrapping quotation marks and with only one possessive apostrophe) will be used wherever the variables name1 or name2 are used in expressions. Both techniques for including apostrophes in the text sequence have the same result.

Enter text...

This selection opens a dialog box prompting you for text. After you enter it and click OK, the text will be entered at the cursor, wrapped with quotation marks. This is an easy way to resolve any issues about internal quotation marks, as the dialog box will convert the text into the necessary character sequence required to generate your desired text.

Example

Explanation

This will produce a converted character sequence that produces a valid string and insert it to the expression at the insertion point.

concat(t, u, ...)

This concatenates a series of text sequences together.

Example

Explanation

Each of the text sequences in the input are run together and combined. If [direction] is 'North' then name will be Seequent_North_Region. If [direction] is 'South' then name will be Seequent_South_Region.

startswith(t, 'prefix')

This function returns true if the text sequence t starts with prefix, and false otherwise. This is case insensitive; 'prefix' will match 'PREFIX'.

Example

Explanation

filter will be true if [name] starts with Seequent.

endswith(t, 'suffix')

This function returns true if the text sequence t ends with suffix, and false otherwise. This is case insensitive; 'suffix' will match 'SUFFIX'.

Example

Explanation

filter will be true if [name] ends with Region.

contains(t, 'part')

This function returns true if the text sequence t contains part somewhere within, and false otherwise. This is case insensitive; 'part' will match 'PART'.

Example

Explanation

filter will be true if [name] contains North somewhere within the character sequence.

like(t, 'pattern')

This function returns true if the text sequence t matches pattern, where [pattern] is follows SQL-style LIKE matching rules. This is case insensitive, and pattern must match the whole of t, not just a portion of it. Use _ as a wildcard for a single character, and % as a wildcard for any number of characters (including no characters).

Example

Explanation

filter will be true if [name] matches the pattern %Seequent_Region%. Examples of [name] that will match include:

SEEQUENT1Region
SEEQUENT1REGION
Seequent2region
NorthernSeequent1Region
SEEQUENT3regionExtra
#seequentXregion#

Examples that will not match include:

Seequent12Region
SeequentReg1ion
SeequentRegion

regexp(t, 'pattern')

This function returns true if the text sequence t matches pattern, where [pattern] is follows regular expression matching rules. This is case insensitive.

Example

Explanation

filter will be true if [name] matches the regexp pattern Seequent.Region. Examples of [name] that will match include:

SEEQUENT1Region
SEEQUENT1REGION
Seequent2region
NorthernSeequent1Region
SEEQUENT3regionExtra
#seequentXregion#

Examples that will not match include:

Seequent12Region
SeequentReg1ion
SeequentRegion

Date/Time

'now' Current timestamp

Use this item to add the current date-and-timestamp at the insertion point.

Example

Explanation

While entering an expression, the 'now' selection has been chosen and a date-and-timestamp has been entered at the insertion point.

'today' Current date

Use this item to add the current datestamp at the insertion point.

Example

Explanation

While entering an expression, the 'today' selection has been chosen and a date-and-timestamp has been entered at the insertion point.

dateonly(timestamp)

This function takes a date-and-timestamp and cuts off the timestamp to leave just the date.

Example

Explanation

While the [past] variable has a full date-and-timestamp, the dateonly function strips the time off and leaves just the date.

Pick timestamp...

This selection opens a dialog box prompting you for a date and a time that will be entered at the insertion point when you click OK.

Example

Explanation

Use the year picker, month picker, date selector and Time field to specify a date and time. If the above date is entered, it will be represented in the expression as @2020-01-22 00:00:00.

Pick date...

This selection opens a dialog box prompting you for a date that will be entered at the insertion point when you click OK.

Example

Explanation

Use the year picker, month picker and date selector to specify a date. If the above date is entered, it will be represented in the expression as @2020-01-22.

Unit Conversion

Mass/weight...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

When you have selected the two units, the dialog box disappears and the conversion function you require will have been inserted into the expression at the cursor, and the cursor repositioned so you can enter the source of the value to be converted.

Example

Explanation

The troy_oz_to_g function has been entered by the dialog box, and the variable [troyOz] has been entered as the input. The numeric calculation grams will be given the output of the troy_oz_to_g function.

Distance...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

Example

Explanation

The ft_to_m function has been entered by the dialog box, and the variable [feet] has been entered as the input. The numeric calculation metres will be given the output of theft_to_m function.

Area...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

Example

Explanation

The ha_to_acre function has been entered by the dialog box, and the variable [hectares] has been entered as the input. The numeric calculation acres will be given the output of theha_to_acre function.

Volume...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

Example

Explanation

The acre_ft_to_m3 function has been entered by the dialog box, and the variable [acre-ft] has been entered as the input. The numeric calculation volm3 will be given the output of theacre_ft_to_m3 function.

Temperature...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

Example

Explanation

The degF_to_K function has been entered by the dialog box, and the variable [fahrenheit] has been entered as the input. The numeric calculation Kelvin will be given the output of thedegF_to_K function.

Pressure...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

Example

Explanation

The psi_to_kPa function has been entered by the dialog box, and the variable [pressure_psi] has been entered as the input. The numeric calculation pressure_kPa will be given the output of thepsi_to_kPa function.

Energy...

This selection opens a dialog box prompting for the From Unit and To Unit for the conversion.

Example

Explanation

The MJ_to_kWh function has been entered by the dialog box, and the variable [MegaJoules] has been entered as the input. The numeric calculation kiloWatt Hours will be given the output of the MJ_to_kWh function.

Got a question? Visit the Seequent forums or Seequent support