IForest Anomaly Detection - Platform For AI - Alibaba Cloud Documentation Center

The IForest Anomaly Detection component detects outliers in tabular datasets using the Isolation Forest (IForest) algorithm. IForest works by randomly selecting a feature and splitting the data between the feature's minimum and maximum values — anomalous data points require fewer splits to isolate, producing shorter path lengths. The component uses subsampling to reduce computational complexity while maintaining detection accuracy.

Configure the component in Designer or through Python code using the PyAlink Script component.

How it works

IForest builds an ensemble of random decision trees. For each tree, it randomly selects a feature and a split value, then recursively partitions the data. Points that are isolated quickly (short paths) receive high outlier scores. After scoring all data points, the component applies an outlier threshold to label them as outliers or normal.

Two parameters directly control detection behavior:

Number of trees in the model (numTrees, default: 100) — more trees reduce score noise by averaging results across a larger ensemble. Start with the default value of 100; increase it if scores appear unstable across runs.
Number of rows sampled per tree (subsamplingSize, default: 256) — relates to the expected density of anomalies. Decrease this value if you expect a higher anomaly rate.

Configure the component

Use Designer

Configure the component parameters on the workflow page in Designer.

Fields setting

Parameter	Description
Feature columns	Feature columns for training. Mutually exclusive with Vector column and Tensor column — use only one to specify input features.
Group columns	Columns for grouping data.
Tensor column	Name of the tensor column. Mutually exclusive with Vector column and Feature columns.
Vector column	Name of the vector column. Mutually exclusive with Tensor column and Feature columns.

Parameter settings

Parameter	Default	Range	Description
Prediction result column	—	—	Name of the output column that stores the prediction result (outlier or normal).
Prediction details column	—	—	Name of the output column that stores the raw outlier score for each data point.
Outlier score threshold	—	—	Data points with scores above this value are labeled as outliers. A higher threshold means fewer points are flagged.
Maximum number of outliers per group	—	—	Maximum number of outliers to detect per group.
Maximum ratio of outliers	—	—	Maximum proportion of data points that can be labeled as outliers. For example, set to `0.05` to flag at most 5% of data.
Maximum number of samples per group	—	—	Maximum number of samples per group.
Number of trees in the model	100	—	Number of trees in the ensemble. More trees reduce score noise.
Number of rows sampled per tree	256	[2, 100000]	Rows sampled per tree.
Number of threads	1	—	Number of threads for the component.

Execution tuning

Parameter	Default	Range	Description
Number of workers	—	[1, 9999]	Number of workers. Use with Memory per worker.
Memory per worker (MB)	—	[1024, 65536]	Memory allocated to each worker, in MB.

Use Python code

Configure parameters using the PyAlink Script component. For more information, see PyAlink Script.

Parameters

Parameter	Required	Default	Description
`predictionCol`	Yes	—	Name of the output column for the prediction result.
`predictionDetailCol`	Yes	—	Name of the output column for prediction details (raw outlier scores).
`featureCols`	No	Select All	Feature column names. Array type.
`groupCols`	No	None	Group column names. Supports multiple columns.
`outlierThreshold`	No	None	Outlier score threshold. Points above this value are labeled as outliers.
`maxOutlierRatio`	No	None	Maximum proportion of points to label as outliers.
`maxOutlierNumPerGroup`	No	None	Maximum number of outliers per group.
`maxSampleNumPerGroup`	No	None	Maximum number of samples per group.
`numTrees`	No	100	Number of trees in the ensemble.
`subsamplingSize`	No	256	Rows sampled per tree. Range: [2, 100000].
`numThreads`	No	1	Number of threads.
`tensorCol`	No	None	Tensor column name.
`vectorCol`	No	None	Vector column name.

Example

The following example detects outliers in a small dataset using IForestOutlierBatchOp. It sets an outlierThreshold of 3.0 and specifies val as the only feature column. The prediction result is written to pred and the raw scores to pred_detail.

from pyalink.alink import *
import pandas as pd

df = pd.DataFrame([
    [0.73, 0],
    [0.24, 0],
    [0.63, 0],
    [0.55, 0],
    [0.73, 0],
    [0.41, 0]
])

dataOp = BatchOperator.fromDataframe(df, schemaStr='val double, label int')

outlierOp = IForestOutlierBatchOp()\
    .setFeatureCols(["val"])\
    .setOutlierThreshold(3.0)\
    .setPredictionCol("pred")\
    .setPredictionDetailCol("pred_detail")

outlierOp.print()

Constraints and guidance

Feature input is mutually exclusive: Set only one of Feature columns, Vector column, or Tensor column. Setting more than one causes an error.
Choosing a threshold: Outlier scores are dimensionless path-length metrics. If you do not have a prior expectation for the threshold, run the component once without setting outlierThreshold to inspect the score distribution in predictionDetailCol, then choose a cutoff based on the distribution.
Controlling the anomaly rate: Use maxOutlierRatio when you have a known or estimated anomaly rate in your dataset. This acts as a cap regardless of the threshold setting.

What's next

PyAlink Script