Main Content

LocalOutlierFactor

Local outlier factor model for anomaly detection

    Description

    Use a local outlier factor model object LocalOutlierFactor for anomaly detection.

    • Outlier detection (detecting anomalies in training data) — Detect anomalies in training data by using the lof function. The lof function creates a LocalOutlierFactor object and returns anomaly indicators and scores (local outlier factor values) for the training data.

    • Novelty detection (detecting anomalies in new data with uncontaminated training data) — Create a LocalOutlierFactor object by passing uncontaminated training data (data with no outliers) to lof, and detect anomalies in new data by passing the object and the new data to the object function isanomaly. The isanomaly function returns anomaly indicators and scores for the new data.

    Creation

    Create a LocalOutlierFactor object by using the lof function.

    Properties

    expand all

    This property is read-only.

    Predictors used to train the local outlier factor model, specified as a numeric matrix or a table. Each row of X corresponds to one observation, and each column corresponds to one variable.

    This property is read-only.

    Maximum number of data points in each leaf node of the Kd-tree, specified as a positive integer.

    This property is valid when SearchMethod is 'kdtree'. If SearchMethod is 'exhaustive', the BucketSize value is empty ([]).

    This property is read-only.

    Categorical predictor indices, specified as a vector of positive integers. CategoricalPredictors contains index values indicating that the corresponding predictors are categorical. The index values are between 1 and p, where p is the number of predictors used to train the model. If none of the predictors are categorical, then this property is empty ([]).

    This property is read-only.

    Fraction of anomalies in the training data, specified as a numeric scalar in the range [0,1].

    • If the ContaminationFraction value is 0, then lof treats all training observations as normal observations, and sets the score threshold (ScoreThreshold property value) to the maximum anomaly score value of the training data.

    • If the ContaminationFraction value is in the range (0,1], then lof determines the threshold value (ScoreThreshold property value) so that the function detects the specified fraction of training observations as anomalies.

    This property is read-only.

    Distance metric, specified as a character vector.

    • If all the predictor variables are continuous (numeric) variables, then the Distance value can be one of these distance metrics.

      ValueDescription
      'euclidean'

      Euclidean distance

      'mahalanobis'

      Mahalanobis distance — The distance uses the covariance matrix stored in the DistParameter property.

      'minkowski'

      Minkowski distance — The distance uses the exponent value stored in the DistParameter property.

      'chebychev'

      Chebychev distance (maximum coordinate difference)

      'cityblock'

      City block distance

      'correlation'

      One minus the sample correlation between observations (treated as sequences of values)

      'cosine'

      One minus the cosine of the included angle between observations (treated as vectors)

      'spearman'

      One minus the sample Spearman's rank correlation between observations (treated as sequences of values)

    • If all the predictor variables are categorical variables, then the Distance value can be one of these distance metrics.

      ValueDescription
      'hamming'

      Hamming distance, which is the percentage of coordinates that differ

      'jaccard'

      One minus the Jaccard coefficient, which is the percentage of nonzero coordinates that differ

    For more information on the various distance metrics, see Distance Metrics.

    This property is read-only.

    Distance metric parameter value for the Mahalanobis or Minkowski distance, specified as a positive scalar. The DistParameter value is empty ([]) for the other distances, indicating that the specified distance metric formula has no parameters.

    • If Distance is 'mahalanobis', then DistParameter is the covariance matrix in the Mahalanobis distance formula. The Cov name-value argument of lof sets this property.

    • If Distance is 'minkowski', then DistParameter is the exponent in the Minkowski distance formula. The Exponent name-value argument of lof sets this property.

    This property is read-only.

    Tie inclusion flag indicating whether LocalOutlierFactor includes all the neighbors whose distance values are equal to the kth smallest distance, specified as logical 0 (false) or 1 (true). If IncludeTies is true, LocalOutlierFactor includes all of these neighbors. Otherwise, LocalOutlierFactor includes exactly k neighbors.

    This property is read-only.

    Number of nearest neighbors in X used to compute local outlier factor values, specified as a positive integer value.

    This property is read-only.

    Predictor variable names, specified as a cell array of character vectors. The order of the elements of PredictorNames corresponds to the order in which the predictor names appear in the training data.

    This property is read-only.

    Threshold for the anomaly score used to identify anomalies in the training data, specified as a nonnegative scalar.

    The software identifies observations with anomaly scores above the threshold as anomalies.

    • The lof function determines the threshold value to detect the specified fraction (ContaminationFraction property) of training observations as anomalies.

    • The isanomaly object function uses the ScoreThreshold property value as the default value of the ScoreThreshold name-value argument.

    This property is read-only.

    Nearest neighbor search method, specified as 'kdtree' or 'exhaustive'.

    • 'kdtree' — This method uses a Kd-tree algorithm to find nearest neighbors. This option is valid when the distance metric (Distance) is one of the following:

      • 'euclidean' — Euclidean distance

      • 'cityblock' — City block distance

      • 'minkowski' — Minkowski distance

      • 'chebychev' — Chebychev distance

    • 'exhaustive' — This method uses the exhaustive search algorithm to find nearest neighbors.

      • When you compute local outlier factor values for X using the lof function, the function finds nearest neighbors by computing the distance values from all points in X to each point in X.

      • When you compute local outlier factor values for new data Xnew using the isanomaly function, the function finds nearest neighbors by computing the distance values from all points in X to each point in Xnew.

    Object Functions

    isanomalyFind anomalies in data using local outlier factor

    Examples

    collapse all

    Detect outliers (anomalies in training data) by using the lof function.

    Load the sample data set NYCHousing2015.

    load NYCHousing2015

    The data set includes 10 variables with information on the sales of properties in New York City in 2015. Display a summary of the data set.

    summary(NYCHousing2015)
    Variables:
    
        BOROUGH: 91446x1 double
    
            Values:
    
                Min          1    
                Median       3    
                Max          5    
    
        NEIGHBORHOOD: 91446x1 cell array of character vectors
    
        BUILDINGCLASSCATEGORY: 91446x1 cell array of character vectors
    
        RESIDENTIALUNITS: 91446x1 double
    
            Values:
    
                Min            0  
                Median         1  
                Max         8759  
    
        COMMERCIALUNITS: 91446x1 double
    
            Values:
    
                Min           0   
                Median        0   
                Max         612   
    
        LANDSQUAREFEET: 91446x1 double
    
            Values:
    
                Min                0
                Median          1700
                Max       2.9306e+07
    
        GROSSSQUAREFEET: 91446x1 double
    
            Values:
    
                Min                0
                Median          1056
                Max       8.9422e+06
    
        YEARBUILT: 91446x1 double
    
            Values:
    
                Min            0  
                Median      1939  
                Max         2016  
    
        SALEPRICE: 91446x1 double
    
            Values:
    
                Min                0
                Median    3.3333e+05
                Max       4.1111e+09
    
        SALEDATE: 91446x1 datetime
    
            Values:
    
                Min       01-Jan-2015
                Median    09-Jul-2015
                Max       31-Dec-2015
    

    Remove nonnumeric variables from NYCHousing2015. The data type of the BOROUGH variable is double, but it is a categorical variable indicating the borough in which the property is located. Remove the BOROUGH variable as well.

    NYCHousing2015 = NYCHousing2015(:,vartype("numeric"));
    NYCHousing2015.BOROUGH = [];

    Train a local outlier factor model for NYCHousing2015. Specify the fraction of anomalies in the training observations as 0.01.

    [Mdl,tf,scores] = lof(NYCHousing2015,ContaminationFraction=0.01);

    Mdl is a LocalOutlierFactor object. lof also returns the anomaly indicators (tf) and anomaly scores (scores) for the training data NYCHousing2015.

    Plot a histogram of the score values. Create a vertical line at the score threshold corresponding to the specified fraction.

    h = histogram(scores,NumBins=50);
    h.Parent.YScale = 'log';
    xline(Mdl.ScoreThreshold,"r-",["Threshold" Mdl.ScoreThreshold]) 

    Figure contains an axes object. The axes object contains 2 objects of type histogram, constantline.

    If you want to identify anomalies with a different contamination fraction (for example, 0.05), you can train a new local outlier factor model.

     [newMdl,newtf,scores] = lof(NYCHousing2015,ContaminationFraction=0.05);
    

    Note that changing the contamination fraction changes the anomaly indicators only, and does not affect the anomaly scores. Therefore, if you do not want to compute the anomaly scores again by using lof, you can obtain a new anomaly indicator with the existing score values.

    Change the fraction of anomalies in the training data to 0.05.

    newContaminationFraction = 0.05;

    Find a new score threshold by using the quantile function.

    newScoreThreshold = quantile(scores,1-newContaminationFraction)
    newScoreThreshold = 6.7493
    

    Obtain a new anomaly indicator.

    newtf = scores > newScoreThreshold;

    Create a LocalOutlierFactor object for uncontaminated training observations by using the lof function. Then detect novelties (anomalies in new data) by passing the object and the new data to the object function isanomaly.

    Load the 1994 census data stored in census1994.mat. The data set consists of demographic data from the US Census Bureau to predict whether an individual makes over $50,000 per year.

    load census1994

    census1994 contains the training data set adultdata and the test data set adulttest. The predictor data must be either all continuous or all categorical to train a LocalOutlierFactor object. Remove nonnumeric variables from adultdata and adulttest.

    adultdata = adultdata(:,vartype("numeric"));
    adulttest = adulttest(:,vartype("numeric"));

    Train a local outlier factor model for adultdata. Assume that adultdata does not contain outliers.

    [Mdl,tf,s] = lof(adultdata);

    Mdl is a LocalOutlierFactor object. lof also returns the anomaly indicators tf and anomaly scores s for the training data adultdata. If you do not specify the ContaminationFraction name-value argument as a value greater than 0, then lof treats all training observations as normal observations, meaning all the values in tf are logical 0 (false). The function sets the score threshold to the maximum score value. Display the threshold value.

    Mdl.ScoreThreshold
    ans = 28.6719
    

    Find anomalies in adulttest by using the trained local outlier factor model.

    [tf_test,s_test] = isanomaly(Mdl,adulttest);

    The isanomaly function returns the anomaly indicators tf_test and scores s_test for adulttest. By default, isanomaly identifies observations with scores above the threshold (Mdl.ScoreThreshold) as anomalies.

    Create histograms for the anomaly scores s and s_test. Create a vertical line at the threshold of the anomaly scores.

    h1 = histogram(s,NumBins=50,Normalization="probability");
    hold on
    h2 = histogram(s_test,h1.BinEdges,Normalization="probability");
    xline(Mdl.ScoreThreshold,"r-",join(["Threshold" Mdl.ScoreThreshold]))
    h1.Parent.YScale = 'log';
    h2.Parent.YScale = 'log';
    legend("Training Data","Test Data",Location="north")
    hold off

    Figure contains an axes object. The axes object contains 3 objects of type histogram, constantline. These objects represent Training Data, Test Data.

    Display the observation index of the anomalies in the test data.

    find(tf_test)
    ans =
    
      0x1 empty double column vector
    

    The anomaly score distribution of the test data is similar to that of the training data, so isanomaly does not detect any anomalies in the test data with the default threshold value. You can specify a different threshold value by using the ScoreThreshold name-value argument. For an example, see Specify Anomaly Score Threshold.

    More About

    expand all

    Tips

    References

    [1] Breunig, Markus M., et al. “LOF: Identifying Density-Based Local Outliers.” Proceedings of the 2000 ACM SIGMOD International Conference on Management of Data, 2000, pp. 93–104.

    Version History

    Introduced in R2022b