Machine Learning Model block: Advanced Topics

This page covers advanced topics related to the Machine Learning Model block.

This page covers the following sections:

ONNX Specification
Supported Model Shapes
Supported Model Data Types
Data Normalization CSV File

ONNX Specification

The current implementation of the Machine Learning Model Block supports the following version of the ONNX specification:

ONNX Version: 1.13.1 down to 1.2
ONNX Opset Version: 18

Supported Model Shapes

This section describes the model shapes that the Machine Learning Model block supports. The shape refers to the dimensions of the model inputs and outputs.

Input Shapes

The following input shapes are supported:

Shape:

N x H x F
N x H
N x F

Where:

N is the batch size and is normally unknown or -1.
H is the history size or number of history points used per prediction. This defines a moving window of the input data, in time. This dimension is assumed to be one if not specified.
F is the number of fields used per prediction. This dimension is assumed to be one if not specified.

NOTE: Refer to the section on "Model Options" on the Configuring the Machine Learning Model block page on how to differentiates between the second and third shape if the shape has only two input dimensions.

Output Shape

The following output shapes are supported:

Shape:

N x P x F
N x P
N x F

Where:

N is the batch size and is normally unknown or -1. This dimension must match the dimension of N on the model inputs.
P is the predicted size or number of future points that are predicted. This dimension is assumed to be one if not specified.
F is the number of fields produced per prediction. This dimension is assumed to be one if not specified.

Output Shape

NOTE: Only N must match between the input shape and output shape. H and F on the model input are separate compared to P and F on the model output. They can be the same but will most likely not be the same.

Supported Model Data Types

The ONNX specification allows for many different input and output data types to be used by models. The Machine Learning Model Block supports only a select subset of the types supported by ONNX.

The following data types are supported:

Data Type:

Floating Point Types: float32, float64
Signed Integer Types: int8, int16, int32, int64
Unsigned Integer Types: uint8, uint16

NOTE: The model data type must not be confused with the block input field data type.
The block input value will be converted to the data type needed by the model internally.

Data Normalization CSV File

To change and configure the Data Normalization for model inputs and outputs, the Machine Learning Model Block allows one to import a CSV file with the required Normalization types and parameters for each input and output.

The normalization file must be in CSV format and must have a ".csv" file extension. It is recommended to match the normalization file name with the model file name although this is not enforced.
For example, if a model has the file name "TrainedModel.onnx" the normalization file can be called "TrainedModel.onnx.csv" or "TrainedModel.csv" and should preferably be in the same folder as the model.

The normalization file contains the normalization information and normalization parameters for the model inputs and outputs.

The normalization file must have the following columns:

Name	Type	Description
name	String	The name of the field on the model input or model output that the normalization applies to.
type	One of: None Z-Score Min-Max	The normalization that must be performed on the value before a model input or after a model output. None: No normalization. Z-Score: Formula: (value - mean)/(standard deviation) Min-Max: Formula: (value - min)/(max - min)
param_1	Value	Depending on the "type" column: None: This value will be ignored and can be empty. Z-Score: Mean value. Min-Max: Minimum value
param_2	Value	Depending on the "type" column: None: This value will be ignored and can be empty. Z-Score: Standard Deviation value. Min-Max: Maximum value

NOTE: The normalization specified for the model output fields must be in the format used to normalize the data.
Although it is specified as normalization, de-normalization will be done on the predicted value before the value is applied to the associated Output Field.
De-normalization is done as the inverse of the normalization formula specified.

Normalization File Example:

An example normalization file is shown below, given the model shapes.

File Name: TrainedModel.onnx
Input Name: input
Input Shape: N x 1 x 3
Output Name: output
Output Shape: N x 5 x 2

Normalization file: TrainedModel_Normalization.csv

name,type,param_1,param_2
input_001,None,,
input_002,Z-Score,988.65,8.23
input_003,Z-Score,9.23,8.63
output_001,Min-Max,10,25
output_002,Z-Score,9.23,8.63

Return to top