function [obj,isAnomaly,scores] = lof(X,varargin)
%LOF Local Outlier Factor.
%   LOFOBJ = LOF(TBL) returns a LocalOutlierFactor object LOFOBJ
%   for data in the table TBL. TBL contains the predictor variables.
%   LOF ignores any rows of TBL that contain missing values.
%
%   LOFOBJ = LOF(X) is an alternative syntax that accepts X as an N-by-P
%   matrix of predictors with one row per observation and one column
%   per predictor. LOF ignores any rows of X that contain missing values.
%
%   [LOFOBJ,ISANOM] = LOF(...) also returns logical array ISANOM with N
%   elements using any of the input arguments in the previous syntaxes.
%   The Jth element of this array is true if the Jth observation (row) in
%   TBL or X is an anomaly.
%
%   [LOFOBJ,ISANOM,SCORES] = LOF(...) also returns numeric array SCORES
%   with N elements, denoting the local outlier factor values. Value close
%   to 1 indicates a normal observation, and a value greater than 1 indicates
%   an anomaly. LOF returns NaN scores for observations with missing data.
%   Observations with NaN scores are not treated as anomalies.
%
%   LOFOBJ = LOF(...,Name=Value) specifies optional parameter name-value
%   arguments:
%       BucketSize     - The maximum number of data points in the leaf
%                        node of the Kd-tree. This argument is valid only
%                        when SearchMethod is 'kdtree'. Default: 50.
%       CategoricalPredictors - List of categorical predictors. LOF supports
%                        all predictors as categorical or no predictors
%                        as categorical. Specify CategoricalPredictors
%                        as 'all' to indicate all predictors are categorical.
%                        Default: for a matrix input X, no categorical
%                        predictors; for a table TBL, predictors are
%                        treated as categorical if they are strings, cell
%                        arrays of character vectors, logical, or unordered
%                        of type 'categorical'.
%       ContaminationFraction - Fraction of anomalies in the data, single
%                        or double scalar between 0 and 1. Default: 0
%       Cov            - A positive definite matrix indicating the
%                        covariance matrix when computing the Mahalanobis
%                        distance. This argument is valid only when
%                        Distance is 'mahalanobis'. Default: The
%                        covariance matrix computed from TBL or X, after
%                        excluding rows that contain any NaNs.
%       Distance       - A character vector, string scalar, specifying the
%                        distance metric. The choices are:
%                          * 'euclidean' - Euclidean distance. This is the
%                          default if there are no categorical predictors.
%                          * 'fasteuclidean' - Euclidean distance computed 
%                          by using an alternative algorithm that saves
%                          time. This faster algorithm can, in some cases,
%                          reduce accuracy.
%                          * 'cityblock' - City Block distance
%                          * 'chebychev' - Chebychev distance
%                          * 'minkowski' - Minkowski distance
%                          * 'mahalanobis' - Mahalanobis distance
%                          * 'cosine' - Cosine distance
%                          * 'correlation' - Correlation distance
%                          * 'spearman' - Spearman distance
%                          * 'hamming' - Hamming distance. This is the
%                          default if all predictors are categorical.
%                          * 'jaccard' - Jaccard distance
%       Exponent       - A positive scalar indicating the exponent of
%                        Minkowski distance. This argument is valid only
%                        when Distance is 'minkowski'. Default: 2.
%       IncludeTies    - A logical value. Use true to include all neighbors
%                        whose distance equal the kth smallest distance.
%                        Use false to include exactly k-nearest neighbors.
%                        Default is false.
%       NumNeighbors   - A positive integer scalar specifying the number of
%                        nearest neighbors in the input data (TBL or X) to
%                        use for computing SCORES.
%                        Default: min(20,n-1) where n is the number of
%                        unique rows in X.
%       PredictorNames - A string/cell array of names for the predictor
%                        variables, in the order in which they appear in X.
%                        Default: {'x1','x2',...}. For a table TBL, these
%                        names must be a subset of the variable names in
%                        TBL, and only the selected variables are used.
%                        Default: all variables.
%       SearchMethod   - Nearest neighbors search method. Value is either:
%                          * 'kdtree' uses a Kd-tree to find nearest
%                               neighbors. 'kdtree' is valid only when the
%                               distance metric is one of the following:
%                                       - 'euclidean'
%                                       - 'cityblock'
%                                       - 'minkowski'
%                                       - 'chebychev'
%                          * 'exhaustive' uses the exhaustive search
%                               algorithm. The distance values from all the
%                               points in the input data (TBL or X) to each
%                               point in the data are computed to find
%                               nearest neighbors.
%                        Default is 'kdtree' when the input data is only
%                        numerical, the number of columns of the input data
%                        is not greater than 10, input data is not sparse
%                        and the distance metric is one of the above 4
%                        metrics; otherwise, default is 'exhaustive'.
%       CacheSize      - A positive scalar or 'maximal'. The default is 
%                        1e3. Applies only when 'Distance' is 
%                        'fasteuclidean'. If numeric, this argument 
%                        specifies the cache size in megabytes (MB) to 
%                        allocate for an intermediate matrix. If 'maximal', 
%                        lof attempts to allocate enough memory for an 
%                        entire intermediate matrix whose size is MX-by-MX 
%                        (MX is the number of rows of the input data X). If 
%                        the specified cache size exceeds the available 
%                        memory, MATLAB issues an out-of-memory error. 
%                        'CacheSize' does not have to be large enough for 
%                        an entire intermediate matrix, but must be at 
%                        least large enough to hold an MX-by-1 vector. 
%                        Otherwise, lof uses 'euclidean' distance.
%

%   Copyright 2021-2023 The MathWorks, Inc.

internal.stats.checkNotTall(upper(mfilename),0,X,varargin{:});

[varargin{:}] = convertStringsToChars(varargin{:});
[obj,isAnomaly,scores] =  LocalOutlierFactor.fitandscore(X,varargin{:});

end


% LocalWords:  LOFOBJ ISANOM
