Configuring the Machine Learning Model block

This section covers how to configure the Machine Learning Model block, including loading an ONNX model, viewing the model information and mapping the block inputs to the correct model inputs.

This page covers the following sections:

Block Configuration

The block is configured through the Property page of the block. To open the property page, either double click the block, or right click the block and select Block Properties.

Import a Model

To import an existing ONNX model, on the "Model" tab, in the "Imported Model" group:

  1. Click the Import button.

  2. In the File Open Dialog that opens, browse to and select the ONNX model (*.onnx) file and click Open to import the selected file.

  3. If the import failed, a dialog will open up to indicate the failure.

When a file is chosen, the application will attempt to load the Model. If the model is valid, the model will be imported. If the model is not valid, the loading will fail.

If the model has been successfully imported, the "Imported Model" information, "Model Options" and "Data Normalization" information will be populated on the page.

NOTE: See the Machine Learning Model block: Advanced Topics for the supported ONNX specification.

Export a Model

To export a previously imported model, on the "Model" tab, in the "Imported Model" group:

  1. Click the Export button.

  2. In the File Open Dialog that opens, browse to and provide the file name of the ONNX model (*.onnx) file and click Save to specify the file.

  3. A dialog will open up to indicate if the export was successful or failed.

The Export button will only be enabled if a valid model is loaded.

The model loaded will be exported to the files specified. Export can fail if the system can not write to the file specified.

When exporting, the ONNX model will be exported exactly the same compared to the original ONNX model that was imported.

Model Options

The "Model Options" group on the "Model" tab allows one to change how quality is handled by the block as well as to resolve ambiguities on the inputs and outputs, if there are any.

These options are changed by clicking on the second column of a row that is editable by the user. The quality option will always be editable. The below section describes when other options will be editable and when they will be read only with informative information only.

The options are:

  • Input Quality: The "On Input Quality Bad" option allows one to specify the behavior of the block when any mapped input has bad quality.
    The options are

    • Set Output Quality Bad: If set, the block will set the quality of all outputs as Bad if any one of the mapped model inputs have Bad quality. The block outputs will be Bad Quality while there are Bad Quality values in the History Window of the affected input.

    • Stop Execution: If set, the block will stop execution when any of the mapped model inputs have Bad quality.

    Unmapped block inputs with Bad quality does not affect the model nor the quality of the block outputs.
    The default option is "Set Output Quality Bad".

  • Model Input Ambiguity: If the shape of the model input only specifies one known dimension in the form of N x A, then the block has no way to determine if A is the number of fields at the current execute time, or if A is a history window for a single field. If this is the case, the input shape is considered ambiguous.
    The "Model Options" group lists all model inputs, and the ones that are ambiguous can be updated to resolve the ambiguity by specifying if the input is either one of:

    • History Window (X Samples): The model input is a single field with a History Window of X samples, where X is the dimension A from the input shape.

    • X Fields: The model input is a list of X fields without any history on the fields, where X is the dimension A from the input shape

    A model input that is not ambiguous will not have the option to change the value. In this case the shape of the model input will be displayed.
    Changing this option will affect the "Data Normalization" group on the current tab.

  • Model Output Ambiguity: Similar to the model input shape, if the shape of the model output only specifies one known dimension in the form of N x B, the input shape is considered ambiguous.
    The "Model Options" group lists all model outputs, and the ones that are ambiguous can be updated to resolve the ambiguity by specifying if the output is either one of:

    • Multi-Field: The model output is a list of fields at a single prediction time.

    • Single-Field: The model output is a single field with multiple prediction times.

    A model output that is not ambiguous will not have the option to change the value. In this case the shape of the model output will be displayed.
    Changing this option will affect the "Data Normalization" group on the current tab.

Data Normalization

The "Data Normalization" group on the "Model" tab allows one to import and export data normalization parameters for the inputs and outputs of the imported model.
This group have the following options:

  • Import Normalization: The "Import" button is used to import data normalization from a CSV file for all model inputs and outputs.
    Refer to the Machine Learning Model block: Advanced Topics page for the format of the Data Normalization file.
    Data Normalization parameters can only be imported if a valid model is imported.
    The CSV file imported must contain normalization information for all of the model inputs and output exactly otherwise the import will fail.

  • Export Normalization: The "Export" button is used to export data normalization from to a CSV file for all model inputs and outputs.
    Data Normalizations parameters can be exported even if no model is imported.
    All Data Normalization parameters of all inputs and outputs are exported into a single file when exported.

  • Normalization Display: Displays the Data Normalization type and the normalization parameters for each model input and output.
    The types are:

    • None: No normalization is done on block input field values passed to the model and no normalization is done on an output when forwarding an output from the model to a block output field.

    • Z-Score: Z-Score or standard score normalization is done on an input value from the block input field value before the value is forwarded to the model.
      On output the inverse or de-normalization is done on model outputs before the value is forwarded to the block output field.
      The parameters are mean (Mean) and standard deviation (STD).

    • Min-Max: Min-Max normalization is done on input and the inverse on output values.
      The parameters are minimum (Min) and maximum (Max).

By default, no normalization will be done on any input or output. If this is the case, the block inputs must already be normalized based on the model expectations.

Map Model Inputs

All Model input fields must be mapped to Block input fields. The mapping is configured on the "Field Mapping" tab.

NOTE: All model input fields must be mapped for the configuration to be complete and valid.

The "Field Mapping" tab has the following sections:

  • Available Input Fields: This is a list of available block input fields that may be mapped to model inputs.
    The input fields are populated by the fields from connected source blocks.
    Only input fields of type Double and Integer will be listed. Input fields of type String will not be listed.

  • Model Inputs: This is a list of model inputs that must be mapped to a suitable block input. The names of these model inputs generated from the name of the model input and the index of the field in the input. The "Mapped Field" column of this list displays the Input Field mapped to this model input, if configured.

From the "Field Mapping" tab, one can map individual fields, one at a time.

Block input fields are mapped to model input fields on this tab using any one of the follow options:

One two fields are mapped, the selection in the "Model Inputs" list will advance to the next entry in the list.

  • Map Button (>)

    1. Select the input field in the "Available Input Fields" list.

    2. Select the model input in the "Model Inputs" list.

    3. Press the > button to map the selected fields.

    One two fields are mapped, the selection in both lists will advance to the next entry in the list.

  • Mouse Double Click

    1. Select the model input in the "Model Inputs" list.

    2. Double click the input field in the "Available Input Fields" list.

Once two fields are mapped, the "Mapped Field" column of the selected model input will be populated with the name of the mapped input field.

Unmap Model Inputs

From the "Field Mapping" tab, one can unmap individual fields, one at a time, or all fields at once.

Previously mapped inputs are unmapped as follow:

  1. Select the mapped model input in the "Model Inputs" list.

  2. Press the < button to unmap the selection.
    Once a mapping is unmapped, the "Mapped Field" column of the "Model Inputs" list will be cleared to indicate that the model input is unmapped.

Unmapping all of the mapped inputs is done as follow:

  1. Press the << button to unmap all of the mappings in the list.

Inspect Block Outputs

The number of block output fields are determined by the loaded model. The names of these outputs are generated from the name of the model outputs and the index of the output on the model.

The "Output Fields" tab contains the following information:

  • Output Fields: This is a list of output fields that the block produces.
    The name of the output field can be changed inside the list if desired. The entered name will be updated to be a valid identifier according to the field naming conventions imposed on all blocks.
    The index of each output is shown in the "Index" column. The format is [T, P] where T is the tag index of the output and P is the future prediction index.

The block will have an output field for each model output field, for each future prediction that the model makes.
The name of the output field will have a zero padded numbered suffix for each future prediction that the model produces. Zero padding is done to three digits.

For example, if a model has a future prediction horizon of five predictions and two fields per prediction, temperature and humidity, then, given the model output name "out":

  • The block will have ten outputs: out_001_001, out_002_001 corresponding to the two fields for the first prediction time, up to out_001_005 and out_002_005 corresponding to the two fields for the last prediction time.

  • The "Output Fields" list will contain the above listed fields.

Accepting or Discarding Changes

The Ok button will accept the changes on the property page and close the window.

The Cancel button will discard the changes on the property page and close the window.

Return to top

Related topics:

  

CSense 2023- Last updated: June 24,2025
Back to Home