AI Regression

The AI Regression activity trains or runs a regression model using ML.NET on data from a staging table, then writes predictions to an output staging table.

Purpose

Use the AI Regression activity to:

• Predict a numeric value (e.g. revenue, cost, quantity) from a set of input features
• Train a regression model on historical data and save it for future use
• Apply a previously trained model to new data to generate predictions

Modes

Mode	Description
Train Model	Trains a new regression model on the input staging table and saves the .onnx model file to the configured file system path
Run Model	Loads a previously trained model from the file system and applies it to the input staging table, writing predictions to the output staging table

Configuration

Mode

Select Train Model or Run Model.

Input Staging Table

The staging table containing the training or prediction data. Column names must not contain spaces, hyphens, semicolons, or brackets.

File System Path

• Train mode: The folder where the trained model file will be saved (as <ActivityName>.onnx).
• Run mode: The full path to the .onnx model file to load.

Algorithm (Train mode only)

The regression algorithm to use. All three are gradient boosting algorithms evaluated with 6-fold cross-validation and produce ONNX-compatible models. The choice affects how the model fits the data, not the training pipeline or output format.

Algorithm	Loss Function	Best For
FastTreeTweedie (default)	Tweedie	Right-skewed targets with many zeros (e.g. amounts, counts, consumption)
FastTree	Squared error (L2)	Continuous, roughly symmetric targets (e.g. scores, durations, percentages)
LightGbm	Squared error (L2)	Large datasets or high-cardinality features where training speed matters
Auto	—	Automatically selects one of the above at runtime based on data characteristics

FastTreeTweedie

Optimises for the Tweedie loss function, designed for compound Poisson-Gamma distributions — the statistical pattern common in financial, actuarial, and ERP-domain data. It handles zero-inflated and heavily skewed targets better than squared-error objectives.

Use when:

• The target column contains many zero values alongside a tail of large positive values.
• The domain is financial, actuarial, usage-based, or any area where "nothing happened" is a valid frequent outcome (e.g. claims amounts, consumption, defect counts).
• You want a sensible default without prior knowledge of the data distribution.

FastTree

Uses squared-error (L2) loss, the classical regression objective. Well-understood, produces predictable gradient updates, and is robust when the target is normally (or near-normally) distributed with no extreme skew.

Use when:

• The target is a continuous numeric value without heavy skew or many zeros (e.g. temperatures, durations, scores, percentages).
• Interpretability and predictable training behaviour matter more than squeezing out extra accuracy on skewed data.
• You want the broadest baseline before experimenting with alternatives.

LightGbm

Uses leaf-wise tree growth (vs. level-wise in FastTree), which is faster on big data and often achieves better accuracy with fewer trees. Handles high-cardinality categorical features natively.

Use when:

• The input staging table is large (many rows) and training time is a concern.
• There are many categorical or high-cardinality columns in the feature set.
• You want to try a second algorithm after FastTree to see if leaf-wise splitting improves R².
• The target distribution is mixed or unknown and you want the most adaptive learner.

Auto

Inspects the target column at runtime and selects the most appropriate algorithm automatically. The selection logic runs before training and is logged to the activity output so you can see which algorithm was chosen and why.

Selection rules (evaluated in order):

1. > 10 000 rows → LightGbm — leaf-wise growth handles large tables faster.
2. Zero ratio > 20% → FastTreeTweedie — zero-inflated target detected.
3. Skewness > 1.0 → FastTreeTweedie — right-skewed distribution detected.
4. Otherwise → FastTree — target appears roughly symmetric.

Use Auto when you are unsure about the data distribution or want a hands-off default that adapts as the underlying data changes over time.

Decision summary

Situation	Recommended Algorithm
Target has many zeros or is right-skewed (counts, amounts)	FastTreeTweedie
Target is continuous and roughly symmetric	FastTree
Large dataset / many features / speed matters	LightGbm
Unknown distribution or want a hands-off default	Auto
Comparing options — run all three and check R² / RMSE	Start with Auto, then override if needed

Output Staging Table (Run mode)

The staging table where predictions are written. Includes all original columns plus a PredictedValue column.

Transforms

A pipeline of pre-processing transforms applied before the model step. Transforms are configured in the visual transform editor. Common transforms include:

• Concatenate — combine multiple numeric columns into a single feature vector
• Drop Columns — remove columns not needed for training
• Convert Type — convert a column to a numeric type
• Normalize — normalize a column to mean 0, variance 1
• One Hot Encoding — encode a categorical column as a numeric vector
• Train Model — the final step that trains or applies the model

Row Filter (optional)

Filter the input data by a column condition before training or inference. Useful for selecting a subset of rows (e.g. only rows where Year = 2024).

Behavior (Train mode)

1. Input data is loaded from the staging table.
2. The transform pipeline is applied.
3. The model is trained with 6-fold cross-validation. Metrics (MAE, MSE, RMSE, R²) are logged.
4. The trained model is saved as <ActivityName>.onnx in the configured folder.

Behavior (Run mode)

1. Input data is loaded from the staging table.
2. The transform pipeline is applied.
3. The model is loaded from the .onnx file.
4. Predictions are generated and written to the output staging table with a PredictedValue column.
5. A sample of 3 prediction rows is logged for verification.

Output Schema (Run mode)

The output staging table contains all non-vector columns from the input data, plus:

Column	Description
PredictedValue	The regression model's predicted value for each row

Usage Notes

• The feature column (used for prediction) and the estimated column (target variable, used in training) are configured within the Train Model transform step in the transform editor.
• Cross-validation metrics are logged at train time. Review them to assess model quality before using the model in production.
• The model file persists across workflow runs. Retrain periodically as data distributions change.

Best Practices

• Always log or review the cross-validation R² before relying on a trained model. A low R² indicates the model is not predictive.
• Separate training and inference workflows — train occasionally (e.g. monthly), run predictions on each data load.
• Use Drop Columns and Normalize transforms to improve model accuracy before the Train Model step.

Choosing an algorithm

1. Start with FastTreeTweedie — it is the default and handles the skewed, zero-heavy data common in ERP/business datasets.
2. If R² is poor on symmetric data, switch to FastTree — it may converge better when the Tweedie assumption does not hold.
3. If training is slow or the dataset is large, try LightGbm — it typically trains faster and can match or beat FastTree accuracy at scale.
4. Use the cross-validation metrics logged by the activity (Average L1, L2, RMS, R²) to compare algorithms objectively on your specific data.

Needs Review

The exact feature column and estimated column configuration within the Train Model transform step should be verified against the current UI, as this is configured visually inside the transforms editor.

JSON Reference

{
  "discriminator": "FastTreeTweedieRegressionWorkflowActivity",
  "activityId": "<uuid>",
  "name": "AI Regression",
  "positionX": 0,
  "positionY": 0,
  "advanceRule": 2,
  "inputStagingTable": "StagingInput",
  "outputStagingTable": "StagingOutput",
  "fsoPath": "/Models/Regression",
  "mode": 0,
  "transforms": [],
  "filter": null,
  "estimatedColumnName": "Revenue",
  "featureColumnName": "Features",
  "algorithm": 0
}

Property	Type	Description
inputStagingTable	string	Corresponds to the Input Staging Table field. The staging table containing training or prediction data.
outputStagingTable	string	Corresponds to the Output Staging Table field. The staging table where predictions are written (used in Run mode).
fsoPath	string	Corresponds to the File System Path field. Folder path (Train mode) or full file path to the .onnx model (Run mode).
mode	integer	Corresponds to the Mode field. 0 = TrainModel, 1 = RunModel.
transforms	array	Corresponds to the Transforms editor. Array of transform objects defining the pre-processing pipeline.
filter	object | null	Corresponds to the Row Filter field. An optional filter applied to input rows before training or inference. null means no filter.
estimatedColumnName	string	The target (label) column name for regression — the column to predict.
featureColumnName	string	The feature vector column name used as model input (typically the output of a Concatenate transform).
algorithm	integer	Corresponds to the Algorithm field. 0 = FastTreeTweedie, 1 = FastTree, 2 = LightGbm, 3 = Auto.