API Reference / algorithms / anomaly /

isolation_forest.py

Isolation Forest - Unsupervised Anomaly Detection Algorithm.

Classes

IsolationForestDetector

class algorithms.anomaly.isolation_forest.IsolationForestDetector(Classifier)

Isolation Forest for unsupervised anomaly detection.

Isolation Forest is a tree-based ensemble method that detects anomalies by isolating observations. Unlike distance-based or density-based approaches, it explicitly isolates anomalies rather than profiling normal points.
Constructor 
__init__(
    self,
    n_estimators: int = 100,
    max_samples: int | str = 'auto',
    contamination: float = 0.1,
    max_features: int | float = 1.0,
    random_state: int | None = None,
)

Overview

The algorithm builds an ensemble of random isolation trees. For each tree:

  1. Randomly select a feature
  2. Randomly select a split value between the min and max of that feature
  3. Recursively partition the data until each point is isolated
Anomalies are isolated quickly (short path lengths) because they are few and different from normal instances.

Theory

The anomaly score for a point x is computed as:

s(x, n) = 2^{-E(h(x))/c(n)}
where:
  • E(h(x)): Average path length of x over all trees
  • c(n): Average path length of unsuccessful search in a BST with n samples
  • n: Number of training samples
Score interpretation:
  • Score ≈ 1.0 → Anomaly (isolated quickly)
  • Score ≈ 0.5 → Normal point
  • Score < 0.5 → Very normal (hard to isolate)

Parameters

n_estimators
int = 100
Number of isolation trees in the ensemble. More trees generally improve accuracy but increase computation time.
max_samples
int, float, or "auto" = "auto"

The number of samples to draw for training each tree:

  • •int: Use exactly this many samples
  • •float: Use max_samples * n_samples samples
  • •"auto": Use min(256, n_samples)
contamination
float = 0.1
Expected proportion of outliers in the dataset. Used to set the decision threshold. Must be in the range (0, 0.5].
max_features
int or float = 1.0

Number of features to consider for each split:

  • •int: Use exactly this many features
  • •float: Use max_features * n_features features
random_state
int or None = None
Random seed for reproducibility. Set for consistent results.

Attributes

trees_
list
Collection of fitted isolation trees.
max_samples_
int
Actual number of samples used per tree after fitting.
max_features_
int
Actual number of features used per tree after fitting.
offset_
float
Offset for computing the decision function.
threshold_
float
Decision threshold separating normal instances from anomalies.
n_features_in_
int
Number of features observed during fit().

Notes

Complexity:

  • Training: O(t \cdot \psi \cdot \log(\psi)) where t = n_estimators, \psi = max_samples
  • Prediction: O(t \cdot \log(\psi)) per sample
When to use Isolation Forest:
  • High-dimensional datasets
  • When you don't know the contamination rate precisely
  • Streaming data (can be updated incrementally)
  • When interpretability is not the primary concern

References

Liu2008
Liu, F.T., Ting, K.M. and Zhou, Z.H. (2008). Isolation Forest. 2008 Eighth IEEE International Conference on Data Mining, pp. 413-422. DOI: 10.1109/ICDM.2008.17
Liu2012
Liu, F.T., Ting, K.M. and Zhou, Z.H. (2012). Isolation-based Anomaly Detection. ACM Transactions on Knowledge Discovery from Data (TKDD), 6(1), Article 3. DOI: 10.1145/2133360.2133363
Hariri2019
Hariri, S., Kind, M.C. and Brunner, R.J. (2019). Extended Isolation Forest. IEEE Transactions on Knowledge and Data Engineering, 33(4), pp. 1479-1489. DOI: 10.1109/TKDE.2019.2947676

See Also

LocalOutlierFactorDetector

Density-based local outlier detection.
OneClassSVMDetector

Support vector based novelty/anomaly detection.
EllipticEnvelopeDetector

Gaussian-based anomaly detection.

Basic usage for anomaly detection:

python 
>>> from tuiml.algorithms.anomaly import IsolationForestDetector
>>> import numpy as np
>>> 
>>> # Create sample data with one anomaly
>>> X = np.array([[1, 2], [2, 3], [3, 3], [2, 2], [10, 10]])
>>> 
>>> # Fit the model
>>> clf = IsolationForestDetector(contamination=0.2, random_state=42)
>>> clf.fit(X)
>>> 
>>> # Predict: -1 for anomalies, 1 for normal points
>>> predictions = clf.predict(X)
>>> print(predictions)
[ 1  1  1  1 -1]
>>> 
>>> # Get anomaly scores (lower = more anomalous)
>>> scores = clf.decision_function(X)

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for algorithm parameters.

get_capabilities (cls) -> List[str]

Return supported capabilities.

get_complexity (cls) -> str

Return complexity analysis.

get_references (cls) -> List[str]

Return academic citations.

fit (self, X: np.ndarray, _y: Optional[np.ndarray]=None) -> 'IsolationForestDetector'

Fit the Isolation Forest model.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Training data.
y
np.ndarray or None = None
Ignored. Present for API consistency.
Returns
self
IsolationForestDetector
Fitted estimator.
decision_function (self, X: np.ndarray) -> np.ndarray

Compute anomaly scores for samples.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
scores
np.ndarray of shape (n_samples,)
Anomaly scores. Lower scores indicate anomalies.
predict (self, X: np.ndarray) -> np.ndarray

Predict if samples are anomalies or not.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
predictions
np.ndarray of shape (n_samples,)
-1 for anomalies, 1 for normal instances.
score_samples (self, X: np.ndarray) -> np.ndarray

Alias for decision_function for compatibility.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input samples.
Returns
scores
np.ndarray of shape (n_samples,)
Anomaly scores.