Functions and Variables for Math Expressions
Variables
Values at the current location:
- Symbols of the selected volumes, specifying the value of the volume at this location.
- Symbols of the selected horizons, specifying the horizon value at this location.
Values representing the current location:
- Variables "nan" and "null" to specify an invalid value at this location.
- Variables "twt_ms" and "twt_s", defined to be the time of a sample in milliseconds or seconds respectively.
- Variables "tvdss_m" and "tvdss_ft", defined to be the true vertical depth (MSL) of a sample in metres or feet respectively.
- Variables "offset", "freq", "channel", "realisation", "semblance", "rotation", "offset_m" and "offset_ft" for those dimensions of a sample, if operating on gathers.
- Variable "linename" to refer to the line name that is currently being processed. Example: for a line named "LINE10", asNumber(sub(linename,5,6)) sets the header value to "10". This variable is only available in Header Maths and is only applicable for 2D volumes.
- Surface location variables ("x", "y", "il", "cl" and "cmp") applicable to the resulting output horizon. These variables are only available in Horizon Maths.
For example, if the output is a 2D horizon, only the cmp location will be available. For a multi-survey horizon, surface locations will only be available if all horizons are of the same type (i.e. cmp is available if all are 2D CMP horizons). - Variables 'pi' and 'e' to define values of π and e.
Defining your own variables
If you are re-using the same value multiple times, or if you wish to organise your equations, defining your own variables can be very useful (and sometimes even more efficient!).
Variable Syntax:
- The variable name appears on the left, followed by an equals sign (=), your expression, and finally a semi-colon (;).
- Example:
a = v1 * 2;
res = a + sin(v1);
- The semi-colon is very important. It must be there to separate the declaration of each variable.
Conditions
You can build complex expressions that result in different behaviour in different situations. Conditional statements take the form:
if (condition, true statement, false statement)
where the true statement is used if the condition is true, or vice-versa. Note that those statements can themselves be arbitrary expressions, such as another conditional statement.
Standard comparison operators may be used, which may be combined with standard boolean operators. You can preface any boolean expression with a! to negate it:
<, >, <=, >= |
Comparison: Less Than, Greater Than, Less Than or Equal, Greater Than or Equal |
!=, == |
Equality: Not Equal, Equal |
&&, ||, ! |
Boolean: AND, OR and NOT |
isnan(...), isnull(...), ismissing(...) |
These functions will evaluate to "true" if the expression is NaN (missing/undefined value), otherwise "false" |
isdefined(...), isvalid(...) |
These functions are the opposite of isnan/isnull/ismissing -- they will evaluate to true if the value is defined at this location (not NaN) |
Warning: Do not use != nan or == nan to check for invalid values in conditional statements. Use one of isnan(), isnull(), isvalid(), etc. functions instead.
Conditional Examples:
If both a and b are less than zero, use the value of c; otherwise use the sum of a and b:
- if (a < 0 && b < 0, c, a + b)
A more-complicated way of writing the same thing, using one conditional inside another:
- if (a < 0, if (b < 0, c, a + b), a + b)
If either a or b are NaN (invalid), use 1500; otherwise use the sum of a and b:
- if (isnan(a) || isnan(b), 1500, a + b)
Combining / Merging
The most natural-seeming way to merge two things together would be to "add" them, as in a + b + c. But this doesn't work, for two reasons.
First, in places where they overlap, that would give you the arithmetic sum of the values at that location -- which is probably not what you intend.
Second, missing values are generally represented by the value NaN (not-a-number). NaN plus any other value remains NaN, so this would have the effect of producing output only at locations where all inputs are defined. This is also probably not what you intend.
To simplify this, Insight provides several functions to make combining easy:
- merge(a, b, c, ...): Combines any number of items, in order of precedence. i.e. where they overlap, the first available value in the list will be used.
- min(a, b, c, ...): Combines any number of items, using the smallest available value
- max(a, b, c, ...): Combines any number of items, using the largest available value
- sum(a, b, c, ...): Arithmetic sum of any number of items, ignoring those that aren't defined at a location
- avg(a, b, c, ...): Arithmetic mean of any number of items, ignoring those that aren't defined at a location
- random(max): Generates a random number between 0 and max (inclusive)
- random(min, max): Generates a random number between min and max (inclusive)
- lerp(v0, v1, t): Linearly interpolates between two inputs (v0, v1) for a parameter (t) in the closed unit interval [0, 1]. Parameter t is clamped between 0 and 1.
- indexOf(v, s1, s2, ...): Returns the 1-based index of the first source (s1,...,sN) which matches the test value (v), or 0 if no match is found.
Operators
The following operators are supported.
Bitwise Operators
Maths operations support a number of bitwise operators. These can be useful for setting flags in headers, but these are not boolean operations. Some care must be taken:
- Only the integer part of a value is considered
- Operations consider which bits are set in that integer value
As a consequence, these differ from conditional operations (if, && etc) which treat any non-zero value as one (true)
a xor b Exclusive OR: Sets bits in the output only where they differ in the inputs, according to the following table.
a & b Bitwise AND: Performs a logical AND on each bit in the inputs, and sets the corresponding output bit to the result.
a | b Bitwise OR: Performs a logical OR on each bit in the inputs, and sets the corresponding output bit to the result.
~a 1's complement: Performs a bitwise NOT, inverting all bits in the value. Note that the integer representation is signed, so this is equivalent to (-a - 1).
* Simplified to show an 8 bit representation
Trigonometry
- sin(x), cos(x), tan(x): Sine, cosine, tangent of a value in radians.
- asin(x), acos(x), atan(x): Arc sine, arc cosine, and arc tangent.
- atan2(y,x): arc tangent - Returns the angle whose tangent is y/x.
- sec(x), cosec(x), cot(x): Secant, cosecant, co-tangent.
- sinh(x), cosh(x), tanh(x), asinh(x), acosh(x), atanh(x): Hyperbolic sine, cosine & tangent; inverse hyperbolic sine cosine & tangent.
Logarithmic
- ln(x): Natural logarithm
- log(x): Log base 10
- lg(x): Log base 2
- exp(x): Exponential (e^x)
- pow(a, b) or a^b: Raise a to the power of b
Statistical / Array
Returns a result for all non-nan (valid) arguments specified. If all values are invalid or missing (nan), the result will be nan.
- avg(a,b,...): Average
- min: Minimum
- max: Maximum
- sum: Sum
- merge: Return the first valid value from the list of arguments.
Rounding
- rint(x): Statistically round to the nearest integer (0.5 will always round towards the nearest even integer)
- round(x): Arithmetically round to the nearest integer (0.5 will always round towards positive infinity)
- floor(x): Floor (round down to the next integer)
- ceil(x): Ceiling (round up to the next integer)
Miscellaneous
- abs(x): Absolute value
- rand(): Random number between 0 and 1
- random(min, max): A random number between min and max
- mod(x,y): The remainder after x is divided by y; this can also be expressed as x % y
- gcd(x,y): The greatest common divisor of x and y
- lcm(x,y): The lowest common multiple of x and y
- sqrt(x): Square root
- signum(x): Sign of a number (-1, 0, or 1)
- toDegrees(x): Convert an angle in radians to degrees
- toRadians(x): Convert an angle in degrees to radians
Complex
- re: Real component
- cmod: Complex modulus (absolute value)
- arg: Argument (angle of complex value, in radians)
- conj: Complex conjugate
- complex(r, i): Construct a complex number from imaginary parts
- polar(r, theta): Construct a complex number from modulus and argument
String Functions
- contains(text, term): Checks whether a contains b (case-sensitive)
- isEmpty(text): Checks whether text contains no characters
- isBlank(text): Checks whether text contains only whitespace
- startsWith(text, term): Checks whether text begins with term
- endsWith(text, term): Checks whether text ends with term
- lower(text): Converts text to lower case
- upper(text): Converts text to upper case
- reverse(text): Reverses the characters in text
- replace(text, target, replacement): Replaces all occurrences of target with replacement in text (case-sensitive)
- formatDecimal(number): Formats number to text with 2 decimal places, and commas separating every 3rd digit
- formatInteger(number): Formats number to text with no decimal places, and commas separating every 3rd digit
- formatScientific(number): Formats number to text in scientific notation, with 3 significant digits
- len(text): Gets the length of text (i.e. the number of characters)
- asNumber(text): Converts the text containing a number (e.g. "1e3") into a number (e.g. 1e3)
- sub(text, start): Gets a subsection of text from the start'th character (inclusive)
- sub(text, start, end): Gets a subsection of text from the start'th character (inclusive) to the end'th character (exclusive)
- find(text, term): Finds the position of the first occurrence of term in text, or -1 if it could not be found
- findLast(text, term): Finds the position of the last occurrence of term in text, or -1 if it could not be found
- trim(text), strip(text): Removes any whitespace at the start and end of text
- trimLeft(text), stripLeft(text): Removes any whitespace at the start of text
- trimRight(text), stripRight(text): Removes any whitespace at the end of text
- padLeft(text, minLength): Adds spaces to the left of text until it is at least minLength characters long
- padRight(text, minLength): Adds spaces to the right of text until it is at least minLength characters long
- padLeft(text, minLength, padText): Adds padText to the left of text until it is at least minLength characters long
- padRight(text, minLength, padText): Adds padText to the right of text until it is at least minLength characters long
Examples
pimp^2 - 2 * simp^2
- Will create a Lambda-Rho volume (pimp squared minus 2 times simp squared)
if (!IsNaN(a), a, b)
- Will use the value of volume "a" for a sample if it exists, otherwise the value of volume "b".
if (d_m < h1, 1500, v1)
- Will make a copy of volume "v1", with any sample shallower than "h1" (a horizon) set to 1500.