PyNomaly 0.3.4__py3-none-any.whl → 0.3.5__py3-none-any.whl

PyNomaly/__init__.py

@@ -0,0 +1,18 @@
+# Authors: Valentino Constantinou <vc@valentino.io>
+# License: Apache 2.0
+
+from PyNomaly.loop import (
+    LocalOutlierProbability,
+    PyNomalyError,
+    ValidationError,
+    ClusterSizeError,
+    MissingValuesError,
+)
+
+__all__ = [
+    "LocalOutlierProbability",
+    "PyNomalyError",
+    "ValidationError",
+    "ClusterSizeError",
+    "MissingValuesError",
+]

PyNomaly/loop.py

@@ -11,10 +11,31 @@ except ImportError:
     pass
 
 __author__ = "Valentino Constantinou"
-__version__ = "0.3.4"
+__version__ = "0.3.5"
 __license__ = "Apache License, Version 2.0"
 
 
+# Custom Exceptions
+class PyNomalyError(Exception):
+    """Base exception for PyNomaly."""
+    pass
+
+
+class ValidationError(PyNomalyError):
+    """Raised when input validation fails."""
+    pass
+
+
+class ClusterSizeError(ValidationError):
+    """Raised when cluster size is smaller than n_neighbors."""
+    pass
+
+
+class MissingValuesError(ValidationError):
+    """Raised when data contains missing values."""
+    pass
+
+
 class Utils:
     @staticmethod
     def emit_progress_bar(progress: str, index: int, total: int) -> str:
@@ -77,217 +98,190 @@ class LocalOutlierProbability(object):
            (2016). 
     """
 
-    class Validate:
+    """
+    Validation methods.
+    These methods validate inputs and raise exceptions or warnings as appropriate.
+    """
+
+    @staticmethod
+    def _convert_to_array(obj: Union["pd.DataFrame", np.ndarray]) -> np.ndarray:
+        """
+        Converts the input data to a numpy array if it is a Pandas DataFrame
+        or validates it is already a numpy array.
+        :param obj: user-provided input data.
+        :return: a vector of values to be used in calculating the local
+        outlier probability.
+        """
+        if obj.__class__.__name__ == "DataFrame":
+            points_vector = obj.values
+            return points_vector
+        elif obj.__class__.__name__ == "ndarray":
+            points_vector = obj
+            return points_vector
+        else:
+            warnings.warn(
+                "Provided data or distance matrix must be in ndarray "
+                "or DataFrame.",
+                UserWarning,
+            )
+            if isinstance(obj, list):
+                points_vector = np.array(obj)
+                return points_vector
+            points_vector = np.array([obj])
+            return points_vector
 
+    def _validate_inputs(self):
         """
-        The Validate class aids in ensuring PyNomaly receives the right set
-        of user inputs for proper execution of the Local Outlier Probability
-        (LoOP) approach. Depending on the desired behavior, either an
-        exception is raised to the user or PyNomaly continues executing
-        albeit with some form of user warning.
+        Validates the inputs provided during initialization to ensure
+        that the needed objects are provided.
+        :return: a tuple of (data, distance_matrix, neighbor_matrix) or
+        raises a warning for invalid inputs.
         """
+        if all(v is None for v in [self.data, self.distance_matrix]):
+            warnings.warn(
+                "Data or a distance matrix must be provided.", UserWarning
+            )
+            return False
+        elif all(v is not None for v in [self.data, self.distance_matrix]):
+            warnings.warn(
+                "Only one of the following may be provided: data or a "
+                "distance matrix (not both).",
+                UserWarning,
+            )
+            return False
+        if self.data is not None:
+            points_vector = self._convert_to_array(self.data)
+            return points_vector, self.distance_matrix, self.neighbor_matrix
+        if all(
+            matrix is not None
+            for matrix in [self.neighbor_matrix, self.distance_matrix]
+        ):
+            dist_vector = self._convert_to_array(self.distance_matrix)
+            neigh_vector = self._convert_to_array(self.neighbor_matrix)
+        else:
+            warnings.warn(
+                "A neighbor index matrix and distance matrix must both be "
+                "provided when not using raw input data.",
+                UserWarning,
+            )
+            return False
+        if self.distance_matrix.shape != self.neighbor_matrix.shape:
+            warnings.warn(
+                "The shape of the distance and neighbor "
+                "index matrices must match.",
+                UserWarning,
+            )
+            return False
+        elif (self.distance_matrix.shape[1] != self.n_neighbors) or (
+            self.neighbor_matrix.shape[1] != self.n_neighbors
+        ):
+            warnings.warn(
+                "The shape of the distance or "
+                "neighbor index matrix does not "
+                "match the number of neighbors "
+                "specified.",
+                UserWarning,
+            )
+            return False
+        return self.data, dist_vector, neigh_vector
+
+    def _check_cluster_size(self) -> None:
+        """
+        Validates the cluster labels to ensure that the smallest cluster
+        size (number of observations in the cluster) is larger than the
+        specified number of neighbors.
+        :raises ClusterSizeError: if any cluster is too small.
+        """
+        c_labels = self._cluster_labels()
+        for cluster_id in set(c_labels):
+            c_size = np.where(c_labels == cluster_id)[0].shape[0]
+            if c_size <= self.n_neighbors:
+                raise ClusterSizeError(
+                    "Number of neighbors specified larger than smallest "
+                    "cluster. Specify a number of neighbors smaller than "
+                    "the smallest cluster size (observations in smallest "
+                    "cluster minus one)."
+                )
 
+    def _check_n_neighbors(self) -> bool:
         """
-        Private methods.
+        Validates the specified number of neighbors to ensure that it is
+        greater than 0 and that the specified value is less than the total
+        number of observations.
+        :return: a boolean indicating whether validation has passed without
+        adjustment.
         """
+        if not self.n_neighbors > 0:
+            self.n_neighbors = 10
+            warnings.warn(
+                "n_neighbors must be greater than 0."
+                " Fit with " + str(self.n_neighbors) + " instead.",
+                UserWarning,
+            )
+            return False
+        elif self.n_neighbors >= self._n_observations():
+            self.n_neighbors = self._n_observations() - 1
+            warnings.warn(
+                "n_neighbors must be less than the number of observations."
+                " Fit with " + str(self.n_neighbors) + " instead.",
+                UserWarning,
+            )
+        return True
 
-        @staticmethod
-        def _data(obj: Union["pd.DataFrame", np.ndarray]) -> np.ndarray:
-            """
-            Validates the input data to ensure it is either a Pandas DataFrame
-            or Numpy array.
-            :param obj: user-provided input data.
-            :return: a vector of values to be used in calculating the local
-            outlier probability.
-            """
-            if obj.__class__.__name__ == "DataFrame":
-                points_vector = obj.values
-                return points_vector
-            elif obj.__class__.__name__ == "ndarray":
-                points_vector = obj
-                return points_vector
-            else:
-                warnings.warn(
-                    "Provided data or distance matrix must be in ndarray "
-                    "or DataFrame.",
-                    UserWarning,
-                )
-                if isinstance(obj, list):
-                    points_vector = np.array(obj)
-                    return points_vector
-                points_vector = np.array([obj])
-                return points_vector
+    def _check_extent(self) -> bool:
+        """
+        Validates the specified extent parameter to ensure it is either 1,
+        2, or 3.
+        :return: a boolean indicating whether validation has passed.
+        """
+        if self.extent not in [1, 2, 3]:
+            warnings.warn(
+                "extent parameter (lambda) must be 1, 2, or 3.", UserWarning
+            )
+            return False
+        return True
 
-        def _inputs(self, obj: "LocalOutlierProbability"):
-            """
-            Validates the inputs provided during initialization to ensure
-            that the needed objects are provided.
-            :param obj: a PyNomaly object.
-            :return: a boolean indicating whether validation has failed or
-            the data, distance matrix, and neighbor matrix.
-            """
-            if all(v is None for v in [obj.data, obj.distance_matrix]):
-                warnings.warn(
-                    "Data or a distance matrix must be provided.", UserWarning
-                )
-                return False
-            elif all(v is not None for v in [obj.data, obj.distance_matrix]):
-                warnings.warn(
-                    "Only one of the following may be provided: data or a "
-                    "distance matrix (not both).",
-                    UserWarning,
-                )
-                return False
-            if obj.data is not None:
-                points_vector = self._data(obj.data)
-                return points_vector, obj.distance_matrix, obj.neighbor_matrix
-            if all(
-                matrix is not None
-                for matrix in [obj.neighbor_matrix, obj.distance_matrix]
-            ):
-                dist_vector = self._data(obj.distance_matrix)
-                neigh_vector = self._data(obj.neighbor_matrix)
-            else:
-                warnings.warn(
-                    "A neighbor index matrix and distance matrix must both be "
-                    "provided when not using raw input data.",
-                    UserWarning,
-                )
-                return False
-            if obj.distance_matrix.shape != obj.neighbor_matrix.shape:
-                warnings.warn(
-                    "The shape of the distance and neighbor "
-                    "index matrices must match.",
-                    UserWarning,
-                )
-                return False
-            elif (obj.distance_matrix.shape[1] != obj.n_neighbors) or (
-                obj.neighbor_matrix.shape[1] != obj.n_neighbors
-            ):
-                warnings.warn(
-                    "The shape of the distance or "
-                    "neighbor index matrix does not "
-                    "match the number of neighbors "
-                    "specified.",
-                    UserWarning,
-                )
-                return False
-            return obj.data, dist_vector, neigh_vector
-
-        @staticmethod
-        def _cluster_size(obj) -> bool:
-            """
-            Validates the cluster labels to ensure that the smallest cluster
-            size (number of observations in the cluster) is larger than the
-            specified number of neighbors.
-            :param obj: a PyNomaly object.
-            :return: a boolean indicating whether validation has passed.
-            """
-            c_labels = obj._cluster_labels()
-            for cluster_id in set(c_labels):
-                c_size = np.where(c_labels == cluster_id)[0].shape[0]
-                if c_size <= obj.n_neighbors:
-                    warnings.warn(
-                        "Number of neighbors specified larger than smallest "
-                        "cluster. Specify a number of neighbors smaller than "
-                        "the smallest cluster size (observations in smallest "
-                        "cluster minus one).",
-                        UserWarning,
-                    )
-                    return False
-            return True
-
-        @staticmethod
-        def _n_neighbors(obj) -> bool:
-            """
-            Validates the specified number of neighbors to ensure that it is
-            greater than 0 and that the specified value is less than the total
-            number of observations.
-            :param obj: a PyNomaly object.
-            :return: a boolean indicating whether validation has passed.
-            """
-            if not obj.n_neighbors > 0:
-                obj.n_neighbors = 10
-                warnings.warn(
-                    "n_neighbors must be greater than 0."
-                    " Fit with " + str(obj.n_neighbors) + " instead.",
-                    UserWarning,
-                )
-                return False
-            elif obj.n_neighbors >= obj._n_observations():
-                obj.n_neighbors = obj._n_observations() - 1
-                warnings.warn(
-                    "n_neighbors must be less than the number of observations."
-                    " Fit with " + str(obj.n_neighbors) + " instead.",
-                    UserWarning,
-                )
-            return True
-
-        @staticmethod
-        def _extent(obj) -> bool:
-            """
-            Validates the specified extent parameter to ensure it is either 1,
-            2, or 3.
-            :param obj: a PyNomaly object.
-            :return: a boolean indicating whether validation has passed.
-            """
-            if obj.extent not in [1, 2, 3]:
-                warnings.warn(
-                    "extent parameter (lambda) must be 1, 2, or 3.", UserWarning
-                )
-                return False
-            return True
-
-        @staticmethod
-        def _missing_values(obj) -> bool:
-            """
-            Validates the provided data to ensure that it contains no
-            missing values.
-            :param obj: a PyNomaly object.
-            :return: a boolean indicating whether validation has passed.
-            """
-            if np.any(np.isnan(obj.data)):
-                warnings.warn(
-                    "Method does not support missing values in input data.", UserWarning
-                )
-                return False
-            return True
-
-        @staticmethod
-        def _fit(obj) -> bool:
-            """
-            Validates that the model was fit prior to calling the stream()
-            method.
-            :param obj: a PyNomaly object.
-            :return: a boolean indicating whether validation has passed.
-            """
-            if obj.is_fit is False:
-                warnings.warn(
-                    "Must fit on historical data by calling fit() prior to "
-                    "calling stream(x).",
-                    UserWarning,
-                )
-                return False
-            return True
-
-        @staticmethod
-        def _no_cluster_labels(obj) -> bool:
-            """
-            Checks to see if cluster labels are attempting to be used in
-            stream() and, if so, calls fit() once again but without cluster
-            labels. As PyNomaly does not accept clustering algorithms as input,
-            the stream approach does not support clustering.
-            :param obj: a PyNomaly object.
-            :return: a boolean indicating whether validation has passed.
-            """
-            if len(set(obj._cluster_labels())) > 1:
-                warnings.warn(
-                    "Stream approach does not support clustered data. "
-                    "Automatically refit using single cluster of points.",
-                    UserWarning,
-                )
-                return False
-            return True
+    def _check_missing_values(self) -> None:
+        """
+        Validates the provided data to ensure that it contains no
+        missing values.
+        :raises MissingValuesError: if data contains NaN values.
+        """
+        if np.any(np.isnan(self.data)):
+            raise MissingValuesError(
+                "Method does not support missing values in input data."
+            )
+
+    def _check_is_fit(self) -> bool:
+        """
+        Checks that the model was fit prior to calling the stream() method.
+        :return: a boolean indicating whether the model has been fit.
+        """
+        if self.is_fit is False:
+            warnings.warn(
+                "Must fit on historical data by calling fit() prior to "
+                "calling stream(x).",
+                UserWarning,
+            )
+            return False
+        return True
+
+    def _check_no_cluster_labels(self) -> bool:
+        """
+        Checks to see if cluster labels are attempting to be used in
+        stream() and, if so, returns False. As PyNomaly does not accept
+        clustering algorithms as input, the stream approach does not
+        support clustering.
+        :return: a boolean indicating whether single cluster (no labels).
+        """
+        if len(set(self._cluster_labels())) > 1:
+            warnings.warn(
+                "Stream approach does not support clustered data. "
+                "Automatically refit using single cluster of points.",
+                UserWarning,
+            )
+            return False
+        return True
 
     """
     Decorators.
@@ -389,8 +383,8 @@ class LocalOutlierProbability(object):
                 "Numba is not available, falling back to pure python mode.", UserWarning
             )
 
-        self.Validate()._inputs(self)
-        self.Validate._extent(self)
+        self._validate_inputs()
+        self._check_extent()
 
     """
     Private methods.
@@ -583,7 +577,7 @@ class LocalOutlierProbability(object):
             [self._n_observations(), self.n_neighbors], 9e10, dtype=float
         )
         indexes = np.full([self._n_observations(), self.n_neighbors], 9e10, dtype=float)
-        self.points_vector = self.Validate._data(self.data)
+        self.points_vector = self._convert_to_array(self.data)
         compute = (
             numba.jit(self._compute_distance_and_neighbor_matrix, cache=True)
             if self.use_numba
@@ -806,13 +800,14 @@ class LocalOutlierProbability(object):
         cluster_labels.
         :return: self, which contains the local outlier probabilities as
         self.local_outlier_probabilities.
+        :raises ClusterSizeError: if any cluster is smaller than n_neighbors.
+        :raises MissingValuesError: if data contains missing values.
         """
 
-        self.Validate._n_neighbors(self)
-        if self.Validate._cluster_size(self) is False:
-            sys.exit()
-        if self.data is not None and self.Validate._missing_values(self) is False:
-            sys.exit()
+        self._check_n_neighbors()
+        self._check_cluster_size()
+        if self.data is not None:
+            self._check_missing_values()
 
         store = self._store()
         if self.data is not None:
@@ -848,19 +843,23 @@ class LocalOutlierProbability(object):
         """
 
         orig_cluster_labels = None
-        if self.Validate._no_cluster_labels(self) is False:
+        if self._check_no_cluster_labels() is False:
             orig_cluster_labels = self.cluster_labels
             self.cluster_labels = np.array([0] * len(self.data))
 
-        if self.Validate._fit(self) is False:
+        if self._check_is_fit() is False:
             self.fit()
 
-        point_vector = self.Validate._data(x)
+        point_vector = self._convert_to_array(x)
         distances = np.full([1, self.n_neighbors], 9e10, dtype=float)
         if self.data is not None:
             matrix = self.points_vector
         else:
             matrix = self.distance_matrix
+            # When using distance matrix mode, x is a scalar distance value.
+            # Extract scalar from array to avoid NumPy assignment errors.
+            if point_vector.size == 1:
+                point_vector = float(point_vector.flat[0])
         for p in range(0, matrix.shape[0]):
             if self.data is not None:
                 d = self._euclidean(matrix[p, :], point_vector)

pynomaly-0.3.5.dist-info/METADATA

@@ -0,0 +1,503 @@
+Metadata-Version: 2.4
+Name: PyNomaly
+Version: 0.3.5
+Summary: A Python 3 implementation of LoOP: Local Outlier Probabilities, a local density based outlier detection method providing an outlier score in the range of [0,1].
+Home-page: https://github.com/vc1492a/PyNomaly
+Download-URL: https://github.com/vc1492a/PyNomaly/archive/0.3.5.tar.gz
+Author: Valentino Constantinou
+Author-email: vc@valentino.io
+License: Apache License, Version 2.0
+Keywords: outlier,anomaly,detection,machine,learning,probability
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: python-utils
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+# PyNomaly
+
+PyNomaly is a Python 3 implementation of LoOP (Local Outlier Probabilities).
+LoOP is a local density based outlier detection method by Kriegel, Kröger, Schubert, and Zimek which provides outlier
+scores in the range of [0,1] that are directly interpretable as the probability of a sample being an outlier. 
+
+PyNomaly is a core library of [deepchecks](https://github.com/deepchecks/deepchecks), [OmniDocBench](https://github.com/opendatalab/OmniDocBench) and [pysad](https://github.com/selimfirat/pysad). 
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![PyPi](https://img.shields.io/badge/pypi-0.3.5-blue.svg)](https://pypi.python.org/pypi/PyNomaly/0.3.5)
+[![Total Downloads](https://static.pepy.tech/badge/pynomaly)](https://pepy.tech/projects/pynomaly)
+[![Monthly Downloads](https://static.pepy.tech/badge/pynomaly/month)](https://pepy.tech/projects/pynomaly)
+![Tests](https://github.com/vc1492a/PyNomaly/actions/workflows/tests.yml/badge.svg)
+[![Coverage Status](https://coveralls.io/repos/github/vc1492a/PyNomaly/badge.svg?branch=main)](https://coveralls.io/github/vc1492a/PyNomaly?branch=main)
+[![JOSS](http://joss.theoj.org/papers/f4d2cfe680768526da7c1f6a2c103266/status.svg)](http://joss.theoj.org/papers/f4d2cfe680768526da7c1f6a2c103266)
+
+The outlier score of each sample is called the Local Outlier Probability.
+It measures the local deviation of density of a given sample with
+respect to its neighbors as Local Outlier Factor (LOF), but provides normalized
+outlier scores in the range [0,1]. These outlier scores are directly interpretable
+as a probability of an object being an outlier. Since Local Outlier Probabilities provides scores in the
+range [0,1], practitioners are free to interpret the results according to the application.
+
+Like LOF, it is local in that the anomaly score depends on how isolated the sample is
+with respect to the surrounding neighborhood. Locality is given by k-nearest neighbors,
+whose distance is used to estimate the local density. By comparing the local density of a sample to the
+local densities of its neighbors, one can identify samples that lie in regions of lower
+density compared to their neighbors and thus identify samples that may be outliers according to their Local
+Outlier Probability.
+
+The authors' 2009 paper detailing LoOP's theory, formulation, and application is provided by
+Ludwig-Maximilians University Munich - Institute for Informatics;
+[LoOP: Local Outlier Probabilities](http://www.dbs.ifi.lmu.de/Publikationen/Papers/LoOP1649.pdf).
+
+## Implementation
+
+This Python 3 implementation uses Numpy and the formulas outlined in
+[LoOP: Local Outlier Probabilities](http://www.dbs.ifi.lmu.de/Publikationen/Papers/LoOP1649.pdf)
+to calculate the Local Outlier Probability of each sample.
+
+## Dependencies
+- Python 3.8 - 3.13
+- numpy >= 1.16.3
+- python-utils >= 2.3.0
+- (optional) numba >= 0.45.1
+
+Numba just-in-time (JIT) compiles the function with calculates the Euclidean 
+distance between observations, providing a reduction in computation time 
+(significantly when a large number of observations are scored). Numba is not a 
+requirement and PyNomaly may still be used solely with numpy if desired
+(details below). 
+
+## Quick Start
+
+First install the package from the Python Package Index:
+
+```shell
+pip install PyNomaly # or pip3 install ... if you're using both Python 3 and 2.
+```
+
+Alternatively, you can use conda to install the package from conda-forge:
+
+```shell
+conda install conda-forge::pynomaly
+```
+Then you can do something like this:
+
+```python
+from PyNomaly import loop
+m = loop.LocalOutlierProbability(data).fit()
+scores = m.local_outlier_probabilities
+print(scores)
+```
+where *data* is a NxM (N rows, M columns; 2-dimensional) set of data as either a Pandas DataFrame or Numpy array.
+
+LocalOutlierProbability sets the *extent* (in integer in value of 1, 2, or 3) and *n_neighbors* (must be greater than 0) parameters with the default
+values of 3 and 10, respectively. You're free to set these parameters on your own as below:
+
+```python
+from PyNomaly import loop
+m = loop.LocalOutlierProbability(data, extent=2, n_neighbors=20).fit()
+scores = m.local_outlier_probabilities
+print(scores)
+```
+
+This implementation of LoOP also includes an optional *cluster_labels* parameter. This is useful in cases where regions
+of varying density occur within the same set of data. When using *cluster_labels*, the Local Outlier Probability of a
+sample is calculated with respect to its cluster assignment.
+
+```python
+from PyNomaly import loop
+from sklearn.cluster import DBSCAN
+db = DBSCAN(eps=0.6, min_samples=50).fit(data)
+m = loop.LocalOutlierProbability(data, extent=2, n_neighbors=20, cluster_labels=list(db.labels_)).fit()
+scores = m.local_outlier_probabilities
+print(scores)
+```
+
+**NOTE**: Unless your data is all the same scale, it may be a good idea to normalize your data with z-scores or another
+normalization scheme prior to using LoOP, especially when working with multiple dimensions of varying scale.
+Users must also appropriately handle missing values prior to using LoOP, as LoOP does not support Pandas
+DataFrames or Numpy arrays with missing values.
+
+### Utilizing Numba and Progress Bars
+
+It may be helpful to use just-in-time (JIT) compilation in the cases where a lot of 
+observations are scored. Numba, a JIT compiler for Python, may be used 
+with PyNomaly by setting `use_numba=True`:
+
+```python
+from PyNomaly import loop
+m = loop.LocalOutlierProbability(data, extent=2, n_neighbors=20, use_numba=True, progress_bar=True).fit()
+scores = m.local_outlier_probabilities
+print(scores)
+```
+
+Numba must be installed if the above to use JIT compilation and improve the 
+speed of multiple calls to `LocalOutlierProbability()`, and PyNomaly has been 
+tested with Numba version 0.45.1. An example of the speed difference that can 
+be realized with using Numba is avaialble in `examples/numba_speed_diff.py`. 
+
+You may also choose to print progress bars _with our without_ the use of numba 
+by passing `progress_bar=True` to the `LocalOutlierProbability()` method as above.
+
+### Choosing Parameters
+
+The *extent* parameter controls the sensitivity of the scoring in practice. The parameter corresponds to
+the statistical notion of an outlier defined as an object deviating more than a given lambda (*extent*)
+times the standard deviation from the mean. A value of 2 implies outliers deviating more than 2 standard deviations
+from the mean, and corresponds to 95.0% in the empirical "three-sigma" rule. The appropriate parameter should be selected
+according to the level of sensitivity needed for the input data and application. The question to ask is whether it is
+more reasonable to assume outliers in your data are 1, 2, or 3 standard deviations from the mean, and select the value
+likely most appropriate to your data and application.
+
+The *n_neighbors* parameter defines the number of neighbors to consider about
+each sample (neighborhood size) when determining its Local Outlier Probability with respect to the density
+of the sample's defined neighborhood. The idea number of neighbors to consider is dependent on the
+input data. However, the notion of an outlier implies it would be considered as such regardless of the number
+of neighbors considered. One potential approach is to use a number of different neighborhood sizes and average
+the results for reach observation. Those observations which rank highly with varying neighborhood sizes are
+more than likely outliers. This is one potential approach of selecting the neighborhood size. Another is to
+select a value proportional to the number of observations, such an odd-valued integer close to the square root
+of the number of observations in your data (*sqrt(n_observations*).
+
+## Iris Data Example
+
+We'll be using the well-known Iris dataset to show LoOP's capabilities. There's a few things you'll need for this
+example beyond the standard prerequisites listed above:
+- matplotlib 2.0.0 or greater
+- PyDataset 0.2.0 or greater
+- scikit-learn 0.18.1 or greater
+
+First, let's import the packages and libraries we will need for this example.
+
+```python
+from PyNomaly import loop
+import pandas as pd
+from pydataset import data
+import numpy as np
+from sklearn.cluster import DBSCAN
+import matplotlib.pyplot as plt
+from mpl_toolkits.mplot3d import Axes3D
+```
+
+Now let's create two sets of Iris data for scoring; one with clustering and the other without.
+
+```python
+# import the data and remove any non-numeric columns
+iris = pd.DataFrame(data('iris').drop(columns=['Species']))
+```
+
+Next, let's cluster the data using DBSCAN and generate two sets of scores. On both cases, we will use the default
+values for both *extent* (0.997) and *n_neighbors* (10).
+
+```python
+db = DBSCAN(eps=0.9, min_samples=10).fit(iris)
+m = loop.LocalOutlierProbability(iris).fit()
+scores_noclust = m.local_outlier_probabilities
+m_clust = loop.LocalOutlierProbability(iris, cluster_labels=list(db.labels_)).fit()
+scores_clust = m_clust.local_outlier_probabilities
+```
+
+Organize the data into two separate Pandas DataFrames.
+
+```python
+iris_clust = pd.DataFrame(iris.copy())
+iris_clust['scores'] = scores_clust
+iris_clust['labels'] = db.labels_
+iris['scores'] = scores_noclust
+```
+
+And finally, let's visualize the scores provided by LoOP in both cases (with and without clustering).
+
+```python
+fig = plt.figure(figsize=(7, 7))
+ax = fig.add_subplot(111, projection='3d')
+ax.scatter(iris['Sepal.Width'], iris['Petal.Width'], iris['Sepal.Length'],
+c=iris['scores'], cmap='seismic', s=50)
+ax.set_xlabel('Sepal.Width')
+ax.set_ylabel('Petal.Width')
+ax.set_zlabel('Sepal.Length')
+plt.show()
+plt.clf()
+plt.cla()
+plt.close()
+
+fig = plt.figure(figsize=(7, 7))
+ax = fig.add_subplot(111, projection='3d')
+ax.scatter(iris_clust['Sepal.Width'], iris_clust['Petal.Width'], iris_clust['Sepal.Length'],
+c=iris_clust['scores'], cmap='seismic', s=50)
+ax.set_xlabel('Sepal.Width')
+ax.set_ylabel('Petal.Width')
+ax.set_zlabel('Sepal.Length')
+plt.show()
+plt.clf()
+plt.cla()
+plt.close()
+
+fig = plt.figure(figsize=(7, 7))
+ax = fig.add_subplot(111, projection='3d')
+ax.scatter(iris_clust['Sepal.Width'], iris_clust['Petal.Width'], iris_clust['Sepal.Length'],
+c=iris_clust['labels'], cmap='Set1', s=50)
+ax.set_xlabel('Sepal.Width')
+ax.set_ylabel('Petal.Width')
+ax.set_zlabel('Sepal.Length')
+plt.show()
+plt.clf()
+plt.cla()
+plt.close()
+```
+
+Your results should look like the following:
+
+**LoOP Scores without Clustering**
+![LoOP Scores without Clustering](https://github.com/vc1492a/PyNomaly/blob/main/images/scores.png)
+
+**LoOP Scores with Clustering**
+![LoOP Scores with Clustering](https://github.com/vc1492a/PyNomaly/blob/main/images/scores_clust.png)
+
+**DBSCAN Cluster Assignments**
+![DBSCAN Cluster Assignments](https://github.com/vc1492a/PyNomaly/blob/main/images/cluster_assignments.png)
+
+
+Note the differences between using LocalOutlierProbability with and without clustering. In the example without clustering, samples are
+scored according to the distribution of the entire data set. In the example with clustering, each sample is scored
+according to the distribution of each cluster. Which approach is suitable depends on the use case.
+
+**NOTE**: Data was not normalized in this example, but it's probably a good idea to do so in practice.
+
+## Using Numpy
+
+When using numpy, make sure to use 2-dimensional arrays in tabular format:
+
+```python
+data = np.array([
+    [43.3, 30.2, 90.2],
+    [62.9, 58.3, 49.3],
+    [55.2, 56.2, 134.2],
+    [48.6, 80.3, 50.3],
+    [67.1, 60.0, 55.9],
+    [421.5, 90.3, 50.0]
+])
+
+scores = loop.LocalOutlierProbability(data, n_neighbors=3).fit().local_outlier_probabilities
+print(scores)
+
+```
+
+The shape of the input array shape corresponds to the rows (observations) and columns (features) in the data:
+
+```python
+print(data.shape)
+# (6,3), which matches number of observations and features in the above example
+```
+
+Similar to the above:
+
+```python
+data = np.random.rand(100, 5)
+scores = loop.LocalOutlierProbability(data).fit().local_outlier_probabilities
+print(scores)
+```
+
+## Specifying a Distance Matrix
+
+PyNomaly provides the ability to specify a distance matrix so that any
+distance metric can be used (a neighbor index matrix must also be provided).
+This can be useful when wanting to use a distance other than the euclidean.
+
+Note that in order to maintain alignment with the LoOP definition of closest neighbors, 
+an additional neighbor is added when using [scikit-learn's NearestNeighbors](https://scikit-learn.org/1.5/modules/neighbors.html) since `NearestNeighbors` 
+includes the point itself when calculating the cloest neighbors (whereas the LoOP method does not include distances to point itself). 
+
+```python
+import numpy as np
+from sklearn.neighbors import NearestNeighbors
+
+data = np.array([
+    [43.3, 30.2, 90.2],
+    [62.9, 58.3, 49.3],
+    [55.2, 56.2, 134.2],
+    [48.6, 80.3, 50.3],
+    [67.1, 60.0, 55.9],
+    [421.5, 90.3, 50.0]
+])
+
+# Generate distance and neighbor matrices
+n_neighbors = 3 # the number of neighbors according to the LoOP definition 
+neigh = NearestNeighbors(n_neighbors=n_neighbors+1, metric='hamming')
+neigh.fit(data)
+d, idx = neigh.kneighbors(data, return_distance=True)
+
+# Remove self-distances - you MUST do this to preserve the same results as intended by the definition of LoOP
+indices = np.delete(indices, 0, 1)
+distances = np.delete(distances, 0, 1)
+
+# Fit and return scores
+m = loop.LocalOutlierProbability(distance_matrix=d, neighbor_matrix=idx, n_neighbors=n_neighbors+1).fit()
+scores = m.local_outlier_probabilities
+```
+
+The below visualization shows the results by a few known distance metrics:
+
+**LoOP Scores by Distance Metric**
+![DBSCAN Cluster Assignments](https://github.com/vc1492a/PyNomaly/blob/main/images/scores_by_distance_metric.png)
+
+## Streaming Data
+
+PyNomaly also contains an implementation of Hamlet et. al.'s modifications
+to the original LoOP approach [[4](http://www.tandfonline.com/doi/abs/10.1080/23742917.2016.1226651?journalCode=tsec20)],
+which may be used for applications involving streaming data or where rapid calculations may be necessary.
+First, the standard LoOP algorithm is used on "training" data, with certain attributes of the fitted data
+stored from the original LoOP approach. Then, as new points are considered, these fitted attributes are
+called when calculating the score of the incoming streaming data due to the use of averages from the initial
+fit, such as the use of a global value for the expected value of the probabilistic distance. Despite the potential
+for increased error when compared to the standard approach, it may be effective in streaming applications where
+refitting the standard approach over all points could be computationally expensive.
+
+While the iris dataset is not streaming data, we'll use it in this example by taking the first 120 observations
+as training data and take the remaining 30 observations as a stream, scoring each observation
+individually.
+
+Split the data.
+```python
+iris = iris.sample(frac=1) # shuffle data
+iris_train = iris.iloc[:, 0:4].head(120)
+iris_test = iris.iloc[:, 0:4].tail(30)
+```
+
+Fit to each set.
+```python
+m = loop.LocalOutlierProbability(iris).fit()
+scores_noclust = m.local_outlier_probabilities
+iris['scores'] = scores_noclust
+
+m_train = loop.LocalOutlierProbability(iris_train, n_neighbors=10)
+m_train.fit()
+iris_train_scores = m_train.local_outlier_probabilities
+```
+
+```python
+iris_test_scores = []
+for index, row in iris_test.iterrows():
+    array = np.array([row['Sepal.Length'], row['Sepal.Width'], row['Petal.Length'], row['Petal.Width']])
+    iris_test_scores.append(m_train.stream(array))
+iris_test_scores = np.array(iris_test_scores)
+```
+
+Concatenate the scores and assess.
+
+```python
+iris['stream_scores'] = np.hstack((iris_train_scores, iris_test_scores))
+# iris['scores'] from earlier example
+rmse = np.sqrt(((iris['scores'] - iris['stream_scores']) ** 2).mean(axis=None))
+print(rmse)
+```
+
+The root mean squared error (RMSE) between the two approaches is approximately 0.199 (your scores will vary depending on the data and specification).
+The plot below shows the scores from the stream approach.
+
+```python
+fig = plt.figure(figsize=(7, 7))
+ax = fig.add_subplot(111, projection='3d')
+ax.scatter(iris['Sepal.Width'], iris['Petal.Width'], iris['Sepal.Length'],
+c=iris['stream_scores'], cmap='seismic', s=50)
+ax.set_xlabel('Sepal.Width')
+ax.set_ylabel('Petal.Width')
+ax.set_zlabel('Sepal.Length')
+plt.show()
+plt.clf()
+plt.cla()
+plt.close()
+```
+
+**LoOP Scores using Stream Approach with n=10**
+![LoOP Scores using Stream Approach with n=10](https://github.com/vc1492a/PyNomaly/blob/main/images/scores_stream.png)
+
+### Notes
+When calculating the LoOP score of incoming data, the original fitted scores are not updated.
+In some applications, it may be beneficial to refit the data periodically. The stream functionality
+also assumes that either data or a distance matrix (or value) will be used across in both fitting
+and streaming, with no changes in specification between steps.
+
+## Contributing
+
+Please use the issue tracker to report any erroneous behavior or desired 
+feature requests. 
+
+If you would like to contribute to development, please fork the repository and make 
+any changes to a branch which corresponds to an open issue. Hot fixes 
+and bug fixes can be represented by branches with the prefix `fix/` versus 
+`feature/` for new capabilities or code improvements. Pull requests will 
+then be made from these branches into the repository's `dev` branch 
+prior to being pulled into `main`. 
+
+### Commit Messages and Releases
+
+**Your commit messages are important** - here's why. 
+
+PyNomaly leverages [release-please](https://github.com/googleapis/release-please-action) to help automate the release process using the [Conventional Commits](https://www.conventionalcommits.org/) specification. When pull requests are opened to the `main` branch, release-please will collate the git commit messages and prepare an organized changelog and release notes. This process can be completed because of the Conventional Commits specification. 
+
+Conventional Commits provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages. You can check out examples [here](https://www.conventionalcommits.org/en/v1.0.0/#examples). Make a best effort to use the specification when contributing to Infactory code as it dramatically eases the documentation around releases and their features, breaking changes, bug fixes and documentation updates. 
+
+### Tests
+When contributing, please ensure to run unit tests and add additional tests as 
+necessary if adding new functionality. To run the unit tests, use `pytest`: 
+
+```
+python3 -m pytest --cov=PyNomaly -s -v
+```
+
+To run the tests with Numba enabled, simply set the flag `NUMBA` in `test_loop.py` 
+to `True`. Note that a drop in coverage is expected due to portions of the code 
+being compiled upon code execution. 
+
+## Versioning
+[Semantic versioning](http://semver.org/) is used for this project. If contributing, please conform to semantic
+versioning guidelines when submitting a pull request.
+
+## License
+This project is licensed under the Apache 2.0 license.
+
+## Research
+If citing PyNomaly, use the following: 
+
+```
+@article{Constantinou2018,
+  doi = {10.21105/joss.00845},
+  url = {https://doi.org/10.21105/joss.00845},
+  year  = {2018},
+  month = {oct},
+  publisher = {The Open Journal},
+  volume = {3},
+  number = {30},
+  pages = {845},
+  author = {Valentino Constantinou},
+  title = {{PyNomaly}: Anomaly detection using Local Outlier Probabilities ({LoOP}).},
+  journal = {Journal of Open Source Software}
+}
+```
+
+
+## References
+1. Breunig M., Kriegel H.-P., Ng R., Sander, J. LOF: Identifying Density-based Local Outliers. ACM SIGMOD International Conference on Management of Data (2000). [PDF](http://www.dbs.ifi.lmu.de/Publikationen/Papers/LOF.pdf).
+2. Kriegel H., Kröger P., Schubert E., Zimek A. LoOP: Local Outlier Probabilities. 18th ACM conference on Information and knowledge management, CIKM (2009). [PDF](http://www.dbs.ifi.lmu.de/Publikationen/Papers/LoOP1649.pdf).
+3. Goldstein M., Uchida S. A Comparative Evaluation of Unsupervised Anomaly Detection Algorithms for Multivariate Data. PLoS ONE 11(4): e0152173 (2016).
+4. Hamlet C., Straub J., Russell M., Kerlin S. An incremental and approximate local outlier probability algorithm for intrusion detection and its evaluation. Journal of Cyber Security Technology (2016). [DOI](http://www.tandfonline.com/doi/abs/10.1080/23742917.2016.1226651?journalCode=tsec20).
+
+## Acknowledgements
+- The authors of LoOP (Local Outlier Probabilities)
+    - Hans-Peter Kriegel
+    - Peer Kröger
+    - Erich Schubert
+    - Arthur Zimek
+- [NASA Jet Propulsion Laboratory](https://jpl.nasa.gov/)
+    - [Kyle Hundman](https://github.com/khundman)
+    - [Ian Colwell](https://github.com/iancolwell)

pynomaly-0.3.5.dist-info/RECORD

@@ -0,0 +1,7 @@
+PyNomaly/__init__.py,sha256=TAc8Gsi_DPvsYdWmUTphvkCrw_PDKoRLJ7QMfuNqMpM,360
+PyNomaly/loop.py,sha256=aMG9bo5GNwczenkY6RKjlh3CXsEtRyi8cBIMMN7-NiE,33808
+pynomaly-0.3.5.dist-info/licenses/LICENSE,sha256=xZYfuJFfM57xOlBLbkJmsCwEvw1P6K2t3jI8faTdOMs,563
+pynomaly-0.3.5.dist-info/METADATA,sha256=YoOW9w5rDUoZNozkWUCf8C0UF2NiDve1LKQGn5LsJxc,21891
+pynomaly-0.3.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+pynomaly-0.3.5.dist-info/top_level.txt,sha256=el-HX4RLyBjkh2CW3TK9yXAA54zQOIYVmcJjRbBYKX4,9
+pynomaly-0.3.5.dist-info/RECORD,,

{PyNomaly-0.3.4.dist-info → pynomaly-0.3.5.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.34.2)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

PyNomaly-0.3.4.dist-info/METADATA

@@ -1,17 +0,0 @@
-Metadata-Version: 2.1
-Name: PyNomaly
-Version: 0.3.4
-Summary: A Python 3 implementation of LoOP: Local Outlier Probabilities, a local density based outlier detection method providing an outlier score in the range of [0,1].
-Home-page: https://github.com/vc1492a/PyNomaly
-Author: Valentino Constantinou
-Author-email: vc@valentino.io
-License: Apache License, Version 2.0
-Download-URL: https://github.com/vc1492a/PyNomaly/archive/0.3.4.tar.gz
-Keywords: outlier,anomaly,detection,machine,learning,probability
-Platform: UNKNOWN
-Requires-Dist: numpy
-Requires-Dist: python-utils
-
-UNKNOWN
-
-

PyNomaly-0.3.4.dist-info/RECORD

@@ -1,7 +0,0 @@
-PyNomaly/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-PyNomaly/loop.py,sha256=VLllAa5pOIHZjlI0XuLSpjLzY3tJ_ZTzDCbbIh3VM44,34571
-PyNomaly-0.3.4.dist-info/LICENSE.txt,sha256=xZYfuJFfM57xOlBLbkJmsCwEvw1P6K2t3jI8faTdOMs,563
-PyNomaly-0.3.4.dist-info/METADATA,sha256=xkHaSUSpOnZynE_KfVQAwoBXNOzTpE-IymwuiRdIeos,581
-PyNomaly-0.3.4.dist-info/WHEEL,sha256=g4nMs7d-Xl9-xC9XovUrsDHGXt-FT0E17Yqo92DEfvY,92
-PyNomaly-0.3.4.dist-info/top_level.txt,sha256=el-HX4RLyBjkh2CW3TK9yXAA54zQOIYVmcJjRbBYKX4,9
-PyNomaly-0.3.4.dist-info/RECORD,,