TGL Filter Operators and Functions

Logical operators

Logical operators return a value of either TRUE or FALSE within and expression.

• NOT (NOT) - Use: NOT arg1. Returns the opposite condition. The expression is true only if its operand is false and false if its operand is true.
• AND (AND) - Use: arg1 AND arg2. The expression is true only when both elements are true.
• Inclusive OR (OR) - Use: arg1 OR arg2. The expression is true if either one or both elements are true.

Note: The following logical operators (AND, NOR, BLOT, XOL, BIC, IMP, NMIP) are also defined within the expression builder, but can be built from a combination of the AND, OR and NOT logical operators.

A comparison table of the outcomes from two arguments (1= TRUE, 0= FALSE) for each logical operator is shown below:

Arg 1 a1	Arg 2 a2	AND	OR	NAND	NOR	BLOT	XOR	BIC	IMP	NIMP
0	0	0	0	1	1	0	0	1	1	0
0	1	0	1	1	0	1	1	0	1	0
1	0	0	1	1	0	0	1	0	0	1
1	1	1	1	0	0	0	0	1	1	0

Comparison operators

• Equal to (=) - The expression is true when the operand values are equal.
• Not equal to (/=) - The expression is true when the operand values are not equal.
• Less than (<) - The expression is true when the value of the left operand is less than the value of the right.
• Less than or equal to (<=) - The expression is true when the value of the left operand is less than or equal to the value of the right.
• Greater than (>) - The expression is true when the value of the left operand is greater than the value of the right.
• Greater than or equal to (>=) - The expression is true when the value of the left operand is greater than or equal to the value of the right.

Arithmetic operators

• Plus (+) - The left operand is added to the right operand. Operands must be of the same numeric type, i.e. integer or real.
• Minus (–) - The right operand is subtracted from the left operand. Operands must be of the same numeric type, i.e. integer or real.
• Multiplication (*) - Accepts arithmetic (real or integer) operands and produces the product of them. If one operand is real, the result is also real.
• Division (/) - Divides the first operand by the second. Accepts both real and integer operands and always yields a real result.
• Integer division (DIV) - Divides the first operand by the second and removes any fractional part of the result. Only accepts integer operands and always yields an integer result. e.g. 10 DIV 3 returns 3.
• Modulo (MOD) - Calculates the remainder from the division of the first operand by the second operand. The result is an integer. The result has the sign of the second operand. e.g. 5 MOD -3 returns -2.
• Remainder (REM) - Calculates the remainder from the division of the first operand by the second operand. The result is an integer. The result has the sign of the first operand. e.g. 5 REM -3 returns 2.
• Random (RANDOM) - Use: RANDOM<(arg)>. Calculates random numbers. RANDOM(arg) returns a random integer in the range 0 to the specified argument minus one. RANDOM returns a random number in the range 0 to 1.
• Maximum (MAX) - Returns the maximum value of the argument. You can also compare integer and real operands (integers are converted to real operands before the comparison) and logical and bit string operands (logical operands are converted to a bit string of length 1). Single variables are not directly compatible with bit strings in this context. When you want to use a single variable as a bit string, use the .ALL construct.
• Minimum (MIN) - Returns the minimum value of the argument. The same conditions for MAX apply.
• Exponent (EXP) - Calculates the exponent of its argument. You can use integer and real operands, the result is returned as a real value.
• Absolute value (ABS) - Returns the real value of operand, as the same type (e.g. -23 as 23, -45.6 as 45.6).
• Power (**) - Calculates a in power b, if a is the left operand, and b is the right operand. Operands can be either integer or real.

Category Evaluation

• Concatenation (&) - The right operand and the left operand are joined together, returning a string of the same type. For example, “10” & “11” becomes 1011. Operands must be of the same type, that is, two bit strings or two character strings.
• Membership (IN) - Calculates whether the left operand occurs within the specified range. There are two forms:
• The first tests whether a scalar (integer or real) expression, represented by the left operand, fits into the specified range. Range operands can be either integer or real.
• The second accepts a bit string as the left operand. The second argument is the range of indexes, which specifies the sub-string of this string.

Range operands should be integer expressions or symbolic category names, resolvable with respect to the first operand of the membership operator. The result is true if at least one bit in the specified sub-string is set to 1, and false otherwise.

• Membership negation (NOT IN) - the opposite of the IN operator above.
• Range (..) - Can only be used with other operators. When the symbolic category name contains blanks or non-alphanumeric characters, enclose it in double quotation marks (i.e. representing it as a character string constant).
• Extraction (.) - Extracts sub-strings from bit or character strings. When the symbolic category name contains blanks or non-alphanumeric characters, enclose it in double quotes (i.e. to be represented as a character string constant).
• Bit count (COUNT) - Counts the number of responses above a specified filter limit and returns the result as an integer. This can be used to obtain a logical value for filters and a real value (fixed point number) for weights.
• Numerical arg1 (BITS) - Returns a bit string of the length specified by the first argument and selected bits specified by other arguments. The first argument must be an integer constant. This may be useful for creating masks for variables with long category lists.
• ALL - Returns true if all of the bits in the bit string are set to 1, false otherwise. If the bit string is unrecorded, false is returned.
• ANY - ANY returns true if at least one of the bits in the bit string is set to 1, false otherwise. If the bit string is unrecorded, false is returned.

Conversion

• Conversion to integer (INTEGER) - Converts real and logical operands to integer values.
• Conversion to real (REAL) - Converts integer and logical operands to real values.

Validation Checking

• IIF - Use: IIF (logical_cond, arg1, arg2). IIF is an IF statement that is dependent upon the truth of a condition. This function returns the first argument if the condition is satisfied, and the second argument otherwise. Only one of arguments one and two is actually evaluated. The arguments should have compatible types. The type of the result will be the more general type of the argument types, e.g. if argument is an integer and argument 2 real, the result type is also real. IIF(I, -I, I) returns an absolute value.
• INVALID - Use: INVALID(arg). This function returns true if the argument value is INVALID, false otherwise.
• ISNULL - Use: ISNULL(arg1, arg2). ISNULL substitutes reasonable defaults for unrecorded values. ISNULL returns the first argument when it is not UNRECORDED, i.e. has a value. ISNULL returns the second argument only when the first is UNRECORDED. ISNULL(arg, 0) substitutes 0 instead of unrecorded values.
• MAKENULL - Use: MAKENULL(). MAKENULL always returns the unrecorded value of type integer. It can be used to produce unrecorded values artificially (e.g. in scaled analysis). This example limits the scaled value only to categories from 1 to 3, other categories are not taken into account: IIF(ARG IN 1..3, ARG.I_SCALE, MAKENULL())
• MAKENULLIF - Use: MAKENULLIF(logical_condition, arg2). MAKENULLIF can be considered a short-cut of a more complex construct using Makenull(). MAKENULLIF returns the unrecorded value if the condition is satisfied, and the second argument otherwise. The type of unrecorded value is the same as the second argument, which may have any valid type. This example limits the scaled value only to categories from 1 to 3, other categories are not taken into account: MAKENULLIF(ARG IN 1..3, ARG.I_SCALE)
• UNRECORDED - Use: UNRECORDED(arg). UNRECORDED can be used to test explicitly for NULLs in data. This function returns true if the argument is UNRECORDED, false otherwise.

Variable Properties

• Length (LENGTH) - Use: var_name.LENGTH. The LENGTH attribute allows you to insert the number of categories for a multiple or single type variable into an expression as an integer operand, without knowing what the number is. Example: when the single variable status has 10 categories, status.length returns 10.
• Real scale (R_SCALE) - Use: var.R_SCALE. This attribute has the same functionality as the I_SCALE attribute, but for real scales. Example: where status is a single variable with 5 categories, with an integer list of (0.5,1.0,2.5,2.3,2.4) and a category value 3 in the data status.r_scale returns 2.5.
• Integer scale (I_SCALE) - Use: var.I_SCALE. The I_SCALE attribute can be used with single variables that have a list of integer scales, each of which is associated with a particular category. The attribute returns a value from the I_SCALE list which corresponds to the current value of the variable. If no such value exists in the I_SCALE list, the attribute yields an unrecorded value. Example: where status is a single variable with 5 categories, with an integer list of (5,10,25,23,24) and a category value 3 in the data status.i_scale returns 25.