ExpressionEstimator Class

Definition

public sealed class ExpressionEstimator : Microsoft.ML.IEstimator<Microsoft.ML.Transforms.ExpressionTransformer>

type ExpressionEstimator = class
    interface IEstimator<ExpressionTransformer>

Public NotInheritable Class ExpressionEstimator
Implements IEstimator(Of ExpressionTransformer)

Inheritance

Object

ExpressionEstimator

Implements

IEstimator<ExpressionTransformer>

Remarks

Estimator Characteristics

The resulting ExpressionTransformer creates a new column, named as specified in the output column name parameters, where the expression is applied to the input values. At most one of the input columns can be of type VectorDataViewType, and when the input contains a vector column, the expression is computed independently on each element of the vector, to create a vector output with the same length as that input.

The Expression Language

The language for the expression estimator should be comfortable to a broad range of users. It shares many similarities with some popular languages. It is case sensitive, supports multiple types and has a rich set of operators and functions. It is pure functional, in the sense that there are no mutable values or mutating operations in the language. It does not have, nor need, any exception mechanism, instead producing NA values when a normal value is not appropriate. It is statically typed, but all types are inferred by the compiler.

Syntax

Syntax for the lambda consists of a parameter list followed by either colon (:) or arrow (=>) followed by an expression. The parameter list can be either a single identifier or a comma-separated list of one or more identifiers surrounded by parentheses.

lambda:

• parameter-list : expression
• parameter-list => expression

parameter-list:

• identifier
• ( parameter-names )

parameter-names:

• identifier
• identifier , parameter-names

The expression can use parameters, literals, operators, with-expressions, and functions.

Literals

• The boolean literals are true and false.
• Integer literals may be decimal or hexadecimal (e.g., 0x1234ABCD). They can be suffixed with u or U, indicating unsigned, as well as l or L, indicating long (Int64). The use of u or U is rare and only affects promotion of certain 32 bit hexadecimal values, determining whether the constant is considered a negative Int32 value or a positive Int64 value.
• Floating point literals use the standard syntax, including exponential notation (123.45e-37). They can be suffixed with f or F, indicating single precision, or d or D, indicating double precision. Unlike in C#, the default precision of a floating point literal is single precision. To specify double precision, append d or D.
• Text literals are enclosed in double-quotation marks and support the standard escape mechanisms.

Operators

The operators of the expression language are listed in the following table, in precendence order. Unless otherwise noted, binary operators are left associative and propagate NA values (if either operand value is NA, the result is NA). Generally, overflow of integer values produces NA, while overflow of floating point values produces infinity.

The With Expression

The syntax for the with-expression is:

with-expression:

• with ( assignment-list ; expression )

assignment-list:

• assignment
• assignment , assignment-list

assignment:

• identifier = expression

The with-expression introduces one or more named values. For example, the following expression converts a celcius temperature to fahrenheit, then produces a message based on whether the fahrenheit is too low or high.

c => with(f = c * 9 / 5 + 32 ; f < 60 ? "Too Cold!" : f > 90 ? "Too Hot!" : "Just Right!")

The expression for one assignment may reference the identifiers introduced by previous assignments, as in this example that returns -1, 0, or 1 instead of the messages:

c : with(f = c * 9 / 5 + 32, cold = f < 60, hot = f > 90 ; -float(cold) + float(hot))

As demonstrated above, the with-expression is useful when an expression value is needed multiple times in a larger expression. It is also useful when dealing with complicated or significant constants:

    ticks => with(
        ticksPerSecond = 10000000L,
        ticksPerHour = ticksPerSecond \* 3600,
        ticksPerDay = ticksPerHour \* 24,
        day = ticks / ticksPerDay,
        dayEpoch = 1 ;
        (day + dayEpoch) % 7)

This computes the day of the week from the number of ticks (as an Int64) since the standard .Net DateTime epoch (01/01/0001 in the idealized Gregorian calendar). Assignments are used for number of ticks in a second, number of ticks in an hour, number of ticks in a year, and the day of the week for the epoch. For this example, we want to map Sunday to zero, so, since the epoch is a Monday, we set dayEpoch to 1. If the epoch were changed or we wanted to map a different day of the week to zero, we'd simply change dayEpoch. Note that ticksPerSecond is defined as 10000000L, to make it an Int64 value (8 byte integer). Without the L suffix, ticksPerDay will overflow Int32's range.

Functions

The expression transform supports many useful functions.

General unary functions that can accept an operand of any type are listed in the following table.

The unary conversion functions are listed in the following table. An NA operand produces an NA, or throws if the type does not support it. A conversion that doesn't succeed, or overflow also result in NA or an exception. The most common case of this is when converting from text, which uses the standard conversion parsing. When converting from a floating point value (float or double) to an integer value (Int32 or Int64), the conversion does a truncate operation (round toward zero).

The unary functions that require a numeric operand are listed in the following table. The result type is the same as the operand type. An NA operand value produces NA.

The binary functions that require numeric operands are listed in the following table. When the operand types aren't the same, the operands are promoted to an appropriate type. The result type is the same as the promoted operand type. An NA operand value produces NA.

The unary functions that require a floating point operand are listed in the following table. The result type is the same as the operand type. Overflow produces infinity. Invalid input values produce NA.

The binary functions that require floating point operands are listed in the following table. When the operand types aren't the same, the operands are promoted to an appropriate type. The result type is the same as the promoted operand type. An NA operand value produces NA.

The text functions are listed in the following table.

Methods

Extension Methods

Applies to

See also

• Expression(TransformsCatalog, String, String, String[])