Is this page helpful?

LocalOutlierFactor#

class cuml.neighbors.LocalOutlierFactor( *, n_neighbors=20, algorithm='auto', metric='minkowski', p=2, algo_params=None, metric_params=None, contamination='auto', novelty=False, verbose=False, output_type=None, )[source]#

Unsupervised outlier detection using the Local Outlier Factor (LOF).

The anomaly score of each sample is called the Local Outlier Factor. It measures the local deviation of the density of a given sample with respect to its neighbors. The local density is estimated from the distances to the n_neighbors nearest neighbors, and samples that have a substantially lower density than their neighbors are considered outliers.

Parameters:

n_neighborsint (default=20)

Number of neighbors to use. If it is larger than the number of samples provided, all other samples are used.

algorithmstring (default=’auto’)

The query algorithm to use, see NearestNeighbors for the valid options.

metricstring (default=’minkowski’)

Distance metric to use, see NearestNeighbors for the supported metrics of each algorithm. With the default p=2, 'minkowski' is computed as the euclidean distance.

pfloat (default=2)

Parameter for the Minkowski metric. When p = 1, this is equivalent to manhattan distance (l1), and euclidean distance (l2) for p = 2. For arbitrary p, minkowski distance (lp) is used.

algo_paramsdict, optional (default=None)

Used to configure the nearest neighbor algorithm to be used, see NearestNeighbors.

metric_paramsdict, optional (default = None)

Additional keyword arguments for the metric function. The only supported key is 'p' with the 'minkowski' and 'lp' metrics, where it takes precedence over the p parameter. Other keys raise a ValueError.

contamination‘auto’ or float (default=’auto’)

The proportion of outliers in the data set, used to define the threshold on the scores of the samples.

if 'auto', the threshold is determined as in the original paper (offset_ = -1.5).
if a float, it should be in the range (0, 0.5].

noveltybool (default=False)

By default, LocalOutlierFactor is only meant to be used for outlier detection (novelty=False), and only fit_predict is available. Set to True to use it for novelty detection. In that case predict, decision_function and score_samples should only be used on new unseen data and not on the training set.

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:

negative_outlier_factor_array of shape (n_samples,): The opposite LOF of the training samples. The higher, the more normal. Inliers tend to have a score close to -1, while outliers tend to have a lower score.
n_neighbors_int: The actual number of neighbors used for the neighbor queries.
offset_float: Offset used to obtain binary labels from the raw scores. Samples with a negative_outlier_factor_ below offset_ are detected as outliers.
effective_metric_str: The effective metric used for the distance computation.
n_samples_fit_int: The number of samples in the fitted data.
n_features_in_int: Number of features seen during fit.

Methods

`decision_function`(X)	Shifted opposite of the Local Outlier Factor of X.
`fit`(X[, y])	Fit the local outlier factor detector from the training dataset.
`fit_predict`(X[, y])	Fit the model to the training set X and return the labels.
`predict`(X)	Predict the labels (1 inlier, -1 outlier) of X according to LOF.
`score_samples`(X)	Opposite of the Local Outlier Factor of X.

Notes

The neighbor search runs in single precision, also for float64 inputs, and the scores are returned as float32. With the euclidean metric the distances come from the expanded form of the distance, which loses accuracy when the samples are far from the origin compared to the distances between them. On such data the neighbors, and so the scores, can differ from scikit-learn. Centering the features before fitting reduces this effect.

When several training samples are at the same distance from a query, the selected neighbors can differ from scikit-learn, which changes the score of the samples around the tie.

For additional docs, see scikitlearn’s LocalOutlierFactor.

Examples

>>> import cupy as cp
>>> from cuml.neighbors import LocalOutlierFactor

>>> X = cp.array([[-1.1], [0.2], [101.1], [0.3]], dtype=cp.float32)
>>> lof = LocalOutlierFactor(n_neighbors=2)
>>> lof.fit_predict(X)
array([ 1,  1, -1,  1])

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.

decision_function(X)[source]#

Shifted opposite of the Local Outlier Factor of X.

Only available when novelty=True. The shift offset allows a zero threshold for being an outlier.

Parameters:

Xarray-like or sparse matrix of shape (n_samples, n_features): The query samples.

Returns:

scoresarray of shape (n_samples,): The shifted opposite of the Local Outlier Factor of each sample. Negative scores represent outliers, positive scores represent inliers.

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

Fit the local outlier factor detector from the training dataset.

Parameters:

Xarray-like or sparse matrix of shape (n_samples, n_features): Training data.
yIgnored: Not used, present for API consistency.

Returns:

selfLocalOutlierFactor: The fitted local outlier factor detector.

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

Fit the model to the training set X and return the labels.

Only available when novelty=False.

Parameters:

Xarray-like or sparse matrix of shape (n_samples, n_features): Training data.
yIgnored: Not used, present for API consistency.

Returns:

labelsarray 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

kneighbors( self, X=None, n_neighbors=None, return_distance=True, *, two_pass_precision=False, )[source]#

Query the GPU index for the k nearest neighbors of column vectors in X.

Parameters:

Xarray-like (device or host) shape = (n_samples, n_features): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.
n_neighborsInteger: Number of neighbors to search. If not provided, the n_neighbors from the model instance is used (default=10)
return_distance: Boolean: If False, distances will not be returned
two_pass_precisionbool, optional (default = False): When set to True, a slow second pass will be used to improve the precision of results returned for searches using L2-derived metrics. FAISS uses the Euclidean distance decomposition trick to compute distances in this case, which may result in numerical errors for certain data. In particular, when several samples are close to the query sample (relative to typical inter-sample distances), numerical instability may cause the computed distance between the query and itself to be larger than the computed distance between the query and another sample. As a result, the query is not returned as the nearest neighbor to itself. If this flag is set to true, distances to the query vectors will be recomputed with high precision for all retrieved samples, and the results will be re-sorted accordingly. Note that for large values of k or large numbers of query vectors, this correction becomes impractical in terms of both runtime and memory. It should be used with care and only when strictly necessary (when precise results are critical and samples may be tightly clustered).

Returns:

distancescuDF, CuPy or NumPy object depending on cuML’s output typeconfiguration, shape =(n_samples, n_features): The distances of the k-nearest neighbors for each column vector in X
indicescuDF, CuPy or NumPy object depending on cuML’s output typeconfiguration, shape =(n_samples, n_features): The indices of the k-nearest neighbors for each column vector in X

kneighbors_graph( self, X=None, n_neighbors=None, mode='connectivity', )[source]#

Find the k nearest neighbors of column vectors in X and return as a sparse matrix in CSR format.

Parameters:

Xarray-like (device or host) shape = (n_samples, n_features): Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series.
n_neighborsInteger: Number of neighbors to search. If not provided, the n_neighbors from the model instance is used
modestring (default=’connectivity’): Values in connectivity matrix: ‘connectivity’ returns the connectivity matrix with ones and zeros, ‘distance’ returns the edges as the distances between points with the requested metric.

Returns:

Asparse graph in CSR format, shape = (n_samples, n_samples_fit): n_samples_fit is the number of samples in the fitted data where A[i, j] is assigned the weight of the edge that connects i to j. Values will either be ones/zeros or the selected distance metric. Return types are either cupy’s CSR sparse graph (device) or numpy’s CSR sparse graph (host)

predict(X)[source]#

Predict the labels (1 inlier, -1 outlier) of X according to LOF.

Only available when novelty=True.

Parameters:

Xarray-like or sparse matrix of shape (n_samples, n_features): The query samples.

Returns:

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

score_samples(X)[source]#

Opposite of the Local Outlier Factor of X.

Only available when novelty=True. The argument X is supposed to contain new data: the samples in X are not considered in the neighborhood of any point, so the scores of the training samples are available through negative_outlier_factor_ instead.

Parameters:

Xarray-like or sparse matrix of shape (n_samples, n_features): The query samples.

Returns:

scoresarray of shape (n_samples,): The opposite of the Local Outlier Factor of each sample. The lower, the more abnormal.

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