Is this page helpful?

IsolationForest#

class cuml.ensemble.IsolationForest( *, n_estimators=100, max_samples='auto', max_depth=None, max_features=1.0, bootstrap=False, random_state=None, contamination='auto', verbose=False, output_type=None, )#

GPU-accelerated Isolation Forest for anomaly detection.

Isolation Forest is an unsupervised learning algorithm for anomaly detection that works by isolating anomalies rather than profiling normal data points. It uses the concept that anomalies are few and different, so they are easier to isolate.

The algorithm builds an ensemble of isolation trees where each tree is constructed by randomly selecting a feature and then randomly selecting a split value between the minimum and maximum values of the selected feature. Anomalies have shorter average path lengths in the trees because they are easier to isolate.

Parameters:

n_estimatorsint, default=100

The number of isolation trees in the ensemble.

max_samplesint, float or “auto”, default=”auto”

The number of samples to draw from X to train each isolation tree.

If int, then draw max_samples samples.
If float, then draw max_samples * n_samples samples.
If “auto”, then max_samples=min(256, n_samples).

max_depthint, default=None

Maximum depth of each isolation tree. If None, depth is set to ceil(log2(max_samples)), which is the theoretical maximum depth needed to isolate any sample.

max_featuresfloat or int, default=1.0

The number of features to draw from X to train each isolation tree.

If int, draw exactly max_features features.
If float, draw max_features * n_features features.

bootstrapbool, default=False

If True, individual trees are fit on random subsets of the training data sampled with replacement. Otherwise, sampling is without replacement.

random_stateint, RandomState instance or None, default=None

Controls random row sampling and split selection. Pass an int for reproducible results across runs.

contaminationfloat or “auto”, default=”auto”

The proportion of outliers in the data set, used to define the offset for decision_function and predict.

If "auto", the offset is set to -0.5.
If float, must be in the range (0, 0.5] and the offset is set to the corresponding training-score quantile.

verboseint or boolean, default=False

Sets logging level. It must be one of cuml.common.logger.level_*. See Verbosity Levels for more info.

output_type{None, ‘input’, ‘cupy’, ‘numpy’, ‘cudf’, ‘pandas’}, default=None

Return results and set estimator attributes to the indicated output type. If None, the output type set at the module level (cuml.global_settings.output_type) will be used. See Output Data Type Configuration for more info.

Attributes:

n_features_in_int: Number of features seen during fit.
offset_float: Offset used to compute decision_function from raw anomaly scores.
max_samples_int: The actual number of samples used to train each tree.

Methods

`as_nvforest`(self[, layout, ...])	Create a nvForest model from the Treelite-exported Isolation Forest.
`as_treelite`(self)	Converts this estimator to a Treelite model.
`decision_function`(self, X)	Compute the decision function of X.
`fit`(self, X[, y])	Fit the Isolation Forest model.
`fit_predict`(self, X[, y])	Fit the model and predict on X.
`predict`(self, X)	Predict if samples are anomalies or not.
`score_samples`(self, X)	Compute the anomaly score of X.

Notes

The implementation is based on the original Isolation Forest paper: Liu, F. T., Ting, K. M., & Zhou, Z. H. (2008). Isolation forest. In 2008 Eighth IEEE International Conference on Data Mining (pp. 413-422).

Scoring

The anomaly score is computed as: s(x) = 2^(-E[h(x)] / c(n))

where:

h(x) is the path length of sample x in an isolation tree
E[h(x)] is the average path length over all trees
c(n) is the average path length in an unsuccessful search in a BST

Higher values of s indicate more anomalous samples. score_samples() returns the negative of s, so lower values indicate more anomalous samples. decision_function() subtracts offset_ from these scores; negative decision-function values are predicted as anomalies.

Fitted models can be exported to Treelite with as_treelite() and loaded into nvForest with as_nvforest(). as_sklearn() converts a fitted model into an equivalent sklearn.ensemble.IsolationForest; estimators_samples_ is not available on the converted model because cuML does not record per-tree sample indices.

Examples

>>> import cupy as cp
>>> from cuml.ensemble import IsolationForest

>>> # Create synthetic data with some outliers
>>> rng = cp.random.default_rng(42)
>>> X_inliers = rng.standard_normal((100, 2), dtype=cp.float32)
>>> X_outliers = rng.uniform(low=-4, high=4, size=(20, 2)).astype(cp.float32)
>>> X = cp.vstack([X_inliers, X_outliers])

>>> # Fit the model
>>> clf = IsolationForest(n_estimators=100, random_state=42)
>>> clf.fit(X)
IsolationForest(random_state=42)

>>> # Predict anomalies (-1 for anomaly, 1 for normal)
>>> predictions = clf.predict(X)

>>> # Get anomaly scores (lower = more anomalous)
>>> scores = clf.score_samples(X)

as_nvforest( self, layout='depth_first', default_chunk_size=None, align_bytes=None, )[source]#

Create a nvForest model from the Treelite-exported Isolation Forest.

Returns:

nvforest_modelnvforest.ForestInference: A forest inference model that predicts average path length.

as_sklearn()[source]#

Convert this estimator into an equivalent scikit-learn (or scikit-learn extension) estimator.

Returns:

sklearn.base.BaseEstimator: A scikit-learn compatible estimator instance that mirrors the trained state of the current estimator.

as_treelite(self)[source]#

Converts this estimator to a Treelite model.

The exported Treelite model predicts average path length across the isolation trees.

Returns:

treelite.Model

decision_function(self, X)[source]#

Compute the decision function of X.

The decision function is score_samples(X) - offset_. Negative values indicate anomalies.

Parameters:

Xarray-like of shape (n_samples, n_features): The input samples.

Returns:

scoresndarray of shape (n_samples,): The decision function. Negative values indicate anomalies.

fit(self, X, y=None)[source]#

Fit the Isolation Forest model.

Parameters:

Xarray-like of shape (n_samples, n_features): The input samples. Internally, it will be converted to float32 or float64.
yIgnored: Not used, present for API consistency.

Returns:

selfIsolationForest: Fitted estimator.

fit_predict(self, X, y=None)[source]#

Fit the model and predict on X.

Parameters:

Xarray-like of shape (n_samples, n_features): The input samples.
yIgnored: Not used, present for API consistency.

Returns:

labelsndarray of shape (n_samples,): 1 for inliers, -1 for outliers.

classmethod from_sklearn(model)[source]#

Create a cuml estimator from a scikit-learn estimator.

Parameters:

modelsklearn.base.BaseEstimator: A compatible scikit-learn (or scikit-learn extension) estimator.

Returns:

cls: A new instance of this cuml estimator class that mirrors the state of the input estimator.

Notes

output_type of the estimator is set to “numpy” by default, as these cannot be inferred from training arguments. If something different is required, then please use cuml’s output_type configuration utilities.

get_params(deep=True)[source]#: Returns a dict of all params owned by this class. If the child class has appropriately overridden the _get_param_names method and does not need anything other than what is there in this method, then it doesn’t have to override this method

predict(self, X)[source]#

Predict if samples are anomalies or not.

Returns -1 for anomalies and 1 for normal samples.

Parameters:

Xarray-like of shape (n_samples, n_features): The input samples.

Returns:

labelsndarray of shape (n_samples,): 1 for inliers, -1 for outliers.

score_samples(self, X)[source]#

Compute the anomaly score of X.

Lower scores indicate more anomalous samples. The returned scores are the negative of the anomaly scores defined in the original Isolation Forest paper.

Parameters:

Xarray-like of shape (n_samples, n_features): The input samples.

Returns:

scoresndarray of shape (n_samples,): The anomaly scores. Lower values indicate more anomalous samples. Typical range is approximately [-1.0, 0.0], where values below offset_ are predicted as anomalies.

set_params(**params)[source]#: Accepts a dict of params and updates the corresponding ones owned by this class. If the child class has appropriately overridden the _get_param_names method and does not need anything other than what is, there in this method, then it doesn’t have to override this method