Implement the iforest method of IsoKernel

ikpykit/anomaly/_idkd.py

@@ -28,7 +28,7 @@ class IDKD(OutlierMixin, BaseEstimator):
     similarity with respect to the reference distribution from which the dataset
     was generated.
 
-    This implementation follows the algorithm described in [1]_.
+    This implementation follows the algorithm of Ting et al. (2022).
 
     Parameters
     ----------
@@ -43,12 +43,12 @@ class IDKD(OutlierMixin, BaseEstimator):
         - If float, then draw `max_samples * X.shape[0]` samples.
 
     method : {"inne", "anne", "auto"}, default="inne"
-        Isolation method to use. The original algorithm described in [1]_ uses "inne".
+        Isolation method to use. The original algorithm of Ting et al. (2022) uses "inne".
 
     contamination : {"auto", float}, default="auto"
         The proportion of outliers in the data set.
 
-        - If "auto", the threshold is determined as in [1]_.
+        - If "auto", the threshold is determined as in Ting et al. (2022).
         - If float, the contamination should be in the range (0, 0.5].
 
         Used to define the threshold on the decision function.
@@ -70,7 +70,7 @@ class IDKD(OutlierMixin, BaseEstimator):
 
     References
     ----------
-    .. [1] Kai Ming Ting, Bi-Cun Xu, Washio Takashi, Zhi-Hua Zhou (2022).
+    1. Kai Ming Ting, Bi-Cun Xu, Washio Takashi, Zhi-Hua Zhou (2022).
        "Isolation Distributional Kernel: A new tool for kernel based point and group anomaly detections."
        IEEE Transactions on Knowledge and Data Engineering.
 

ikpykit/anomaly/_iforest.py

@@ -84,12 +84,12 @@ class IForest(OutlierMixin, BaseEstimator):
 
     References
     ----------
-    .. [1] Liu, F. T., Ting, K. M., & Zhou, Z. H. (2008, December). "Isolation forest."
-           In 2008 Eighth IEEE International Conference on Data Mining (pp. 413-422). IEEE.
+    1. Liu, F. T., Ting, K. M., & Zhou, Z. H. (2008, December). "Isolation forest."
+       In 2008 Eighth IEEE International Conference on Data Mining (pp. 413-422). IEEE.
 
-    .. [2] Liu, F. T., Ting, K. M., & Zhou, Z. H. (2012). "Isolation-based
-           anomaly detection." ACM Transactions on Knowledge Discovery from
-           Data (TKDD), 6(1), 1-39.
+    2. Liu, F. T., Ting, K. M., & Zhou, Z. H. (2012). "Isolation-based
+       anomaly detection." ACM Transactions on Knowledge Discovery from
+       Data (TKDD), 6(1), 1-39.
 
     Examples
     --------

ikpykit/anomaly/_inne.py

@@ -62,9 +62,9 @@ class INNE(OutlierMixin, BaseEstimator):
 
     References
     ----------
-    .. [1] T. R. Bandaragoda, K. Ming Ting, D. Albrecht, F. T. Liu, Y. Zhu, and J. R. Wells.
-           "Isolation-based anomaly detection using nearest-neighbor ensembles." In Computational
-           Intelligence, vol. 34, 2018, pp. 968-998.
+    1. T. R. Bandaragoda, K. Ming Ting, D. Albrecht, F. T. Liu, Y. Zhu, and J. R. Wells.
+       "Isolation-based anomaly detection using nearest-neighbor ensembles." In Computational
+       Intelligence, vol. 34, 2018, pp. 968-998.
 
     Examples
     --------

ikpykit/cluster/_idkc.py

@@ -109,7 +109,7 @@ class IDKC(BaseEstimator, ClusterMixin):
 
     References
     ----------
-    .. [1] Ye Zhu, Kai Ming Ting (2023). Kernel-based Clustering via Isolation Distributional Kernel. Information Systems.
+    1. Ye Zhu, Kai Ming Ting (2023). Kernel-based Clustering via Isolation Distributional Kernel. Information Systems.
     """
 
     def __init__(

ikpykit/cluster/_ikahc.py

@@ -74,9 +74,9 @@ class IKAHC(BaseEstimator, ClusterMixin):
 
     References
     ----------
-    .. [1] Xin Han, Ye Zhu, Kai Ming Ting, and Gang Li,
-           "The Impact of Isolation Kernel on Agglomerative Hierarchical Clustering Algorithms",
-           Pattern Recognition, 2023, 139: 109517.
+    1. Xin Han, Ye Zhu, Kai Ming Ting, and Gang Li,
+       "The Impact of Isolation Kernel on Agglomerative Hierarchical Clustering Algorithms",
+       Pattern Recognition, 2023, 139: 109517.
 
     Examples
     --------

ikpykit/cluster/_pskc.py

@@ -77,8 +77,8 @@ class PSKC(BaseEstimator, ClusterMixin):
 
     References
     ----------
-    .. [1] Kai Ming Ting, Jonathan R. Wells, Ye Zhu (2023) "Point-set Kernel Clustering".
-    IEEE Transactions on Knowledge and Data Engineering. Vol.35, 5147-5158.
+    1. Kai Ming Ting, Jonathan R. Wells, Ye Zhu (2023) "Point-set Kernel Clustering".
+       IEEE Transactions on Knowledge and Data Engineering. Vol.35, 5147-5158.
     """
 
     def __init__(

ikpykit/graph/_ikgod.py

@@ -70,7 +70,7 @@ class IKGOD(BaseEstimator):
 
     References
     ----------
-    .. [1] Zhong Zhuang, Kai Ming Ting, Guansong Pang, Shuaibin Song (2023).
+    1. Zhong Zhuang, Kai Ming Ting, Guansong Pang, Shuaibin Song (2023).
        Subgraph Centralization: A Necessary Step for Graph Anomaly Detection.
        Proceedings of The SIAM Conference on Data Mining.
 

ikpykit/graph/_isographkernel.py

@@ -53,8 +53,8 @@ class IsoGraphKernel(BaseEstimator):
 
     References
     ----------
-    .. [1] Bi-Cun Xu, Kai Ming Ting and Yuan Jiang. 2021. "Isolation Graph Kernel".
-    In Proceedings of The Thirty-Fifth AAAI Conference on Artificial Intelligence. 10487-10495.
+    1. Bi-Cun Xu, Kai Ming Ting and Yuan Jiang. 2021. "Isolation Graph Kernel".
+       In Proceedings of The Thirty-Fifth AAAI Conference on Artificial Intelligence. 10487-10495.
 
     Examples
     --------

ikpykit/group/anomaly/_ikgad.py

@@ -70,7 +70,7 @@ class IKGAD(OutlierMixin, BaseEstimator):
 
     References
     ----------
-    .. [1] Kai Ming Ting, Bi-Cun Xu, Washio Takashi, Zhi-Hua Zhou (2022).
+    1. Kai Ming Ting, Bi-Cun Xu, Washio Takashi, Zhi-Hua Zhou (2022).
        Isolation Distributional Kernel: A new tool for kernel based point and group anomaly detections.
        IEEE Transactions on Knowledge and Data Engineering.
 

ikpykit/kernel/_ik_anne.py

@@ -62,9 +62,9 @@ class IK_ANNE(TransformerMixin, BaseEstimator):
 
     References
     ----------
-    .. [1] Qin, X., Ting, K.M., Zhu, Y. and Lee, V.C.
-    "Nearest-neighbour-induced isolation similarity and its impact on density-based clustering".
-    In Proceedings of the AAAI Conference on Artificial Intelligence, Vol. 33, 2019, July, pp. 4755-4762
+    1. Qin, X., Ting, K.M., Zhu, Y. and Lee, V.C.
+       "Nearest-neighbour-induced isolation similarity and its impact on density-based clustering".
+       In Proceedings of the AAAI Conference on Artificial Intelligence, Vol. 33, 2019, July, pp. 4755-4762
     """
 
     def __init__(self, n_estimators=100, max_samples=256, random_state=None):

ikpykit/kernel/_ik_iforest.py

@@ -9,10 +9,13 @@
 """
 
 import numpy as np
+from scipy import sparse
 from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.tree import ExtraTreeRegressor
+from sklearn.utils import check_array
+from sklearn.utils.validation import check_is_fitted, check_random_state
 
 MAX_INT = np.iinfo(np.int32).max
-MIN_FLOAT = np.finfo(float).eps
 
 
 class IK_IForest(TransformerMixin, BaseEstimator):
@@ -24,39 +27,145 @@ class IK_IForest(TransformerMixin, BaseEstimator):
     the characteristics of the local data distribution. It has been shown promising
     performance on density and distance-based classification and clustering problems.
 
-    This version uses iforest to split the data space and calculate Isolation
-    kernel Similarity. Based on this implementation, the feature
-    in the Isolation kernel space is the index of the cell in Voronoi diagrams. Each
-    point is represented as a binary vector such that only the cell the point falling
-    into is 1.
+    This version splits the data space with isolation trees: each tree draws
+    `max_samples` points and cuts them apart with axis-parallel splits at random
+    thresholds, so the cells are boxes rather than the Voronoi cells of `anne` or
+    the hyperspheres of `inne`. The feature in the Isolation kernel space is the
+    index of the leaf a point falls into. Each point is represented as a binary
+    vector such that only the cell the point falls into is 1.
 
     Parameters
     ----------
 
-    n_estimators : int
+    n_estimators : int, default=100
         The number of base estimators in the ensemble.
 
-
-    max_samples : int
+    max_samples : int, default=256
         The number of samples to draw from X to train each base estimator.
 
-            - If int, then draw `max_samples` samples.
-            - If float, then draw `max_samples` * X.shape[0]` samples.
-            - If "auto", then `max_samples=min(8, n_samples)`.
-
     random_state : int, RandomState instance or None, default=None
         Controls the pseudo-randomness of the selection of the feature
         and split values for each branching step and each tree in the forest.
 
         Pass an int for reproducible results across multiple function calls.
         See :term:`Glossary <random_state>`.
 
+    Attributes
+    ----------
+    max_samples_ : int
+        The number of samples actually drawn, capped at the size of X.
+
+    trees_ : list of ExtraTreeRegressor
+        The isolation trees, one per estimator.
+
+    leaf_indices_ : list of ndarray
+        For each tree, a lookup from the tree's own node ids to a dense cell
+        index. A tree grown on `max_samples_` points has at most that many
+        leaves, since every leaf holds at least one of them, so the cell index
+        always fits the same block width the other methods use.
+
+    is_fitted_ : bool
+        Whether the estimator has been fitted.
+
     References
     ----------
-    .. [1] Qin, X., Ting, K.M., Zhu, Y. and Lee, V.C.
-    "Nearest-neighbour-induced isolation similarity and its impact on density-based clustering".
-    In Proceedings of the AAAI Conference on Artificial Intelligence, Vol. 33, 2019, July, pp. 4755-4762
+    1. Kai Ming Ting, Yue Zhu, Zhi-Hua Zhou (2018).
+       "Isolation Kernel and Its Effect on SVM".
+       Proceedings of The ACM SIGKDD Conference on Knowledge Discovery and Data Mining. 2329-2337.
     """
 
-    def __init__(self):
-        pass
+    def __init__(self, n_estimators=100, max_samples=256, random_state=None):
+        self.n_estimators = n_estimators
+        self.max_samples = max_samples
+        self.random_state = random_state
+
+    def fit(self, X, y=None):
+        """Fit the model on data X.
+
+        Parameters
+        ----------
+        X : np.array of shape (n_samples, n_features)
+            The input instances.
+        y : None
+            Ignored. Present for API consistency.
+
+        Returns
+        -------
+        self : object
+            Returns self.
+        """
+        X = check_array(X)
+        n_samples = X.shape[0]
+        self.max_samples_ = min(self.max_samples, n_samples)
+        random_state = check_random_state(self.random_state)
+        self._seeds = random_state.randint(MAX_INT, size=self.n_estimators)
+
+        # The height an isolation tree is grown to. Beyond this the tree can
+        # only separate points that are already rare, which is why the standard
+        # isolation forest stops here as well.
+        max_depth = int(np.ceil(np.log2(max(self.max_samples_, 2))))
+
+        self.trees_ = []
+        self.leaf_indices_ = []
+        for i in range(self.n_estimators):
+            rnd = check_random_state(self._seeds[i])
+            subsample = rnd.choice(n_samples, self.max_samples_, replace=False)
+            tree = ExtraTreeRegressor(
+                max_features=1,
+                splitter="random",
+                max_depth=max_depth,
+                random_state=rnd.randint(MAX_INT),
+            )
+            # The target is noise: an isolation tree splits at random and never
+            # consults it, but the regressor needs one to fit against.
+            tree.fit(X[subsample], rnd.uniform(size=self.max_samples_))
+            self.trees_.append(tree)
+            self.leaf_indices_.append(self._dense_leaf_index(tree))
+
+        self.is_fitted_ = True
+        return self
+
+    @staticmethod
+    def _dense_leaf_index(tree):
+        """Map a tree's leaf node ids onto a contiguous range starting at 0.
+
+        The ids the tree assigns are positions in its node array, so they run
+        past the number of leaves and cannot be used as feature columns.
+        """
+        inner = tree.tree_
+        lookup = np.zeros(inner.node_count, dtype=np.int32)
+        leaves = np.flatnonzero(inner.children_left == -1)
+        lookup[leaves] = np.arange(len(leaves), dtype=np.int32)
+        return lookup
+
+    def transform(self, X):
+        """Compute the isolation kernel feature of X.
+
+        Parameters
+        ----------
+        X: array-like of shape (n_instances, n_features)
+            The input instances.
+
+        Returns
+        -------
+        sparse matrix: The finite binary features based on the kernel feature map.
+            The features are organized as a n_instances by (n_estimators * max_samples_) matrix.
+        """
+        check_is_fitted(self, "is_fitted_")
+        X = check_array(X)
+        n_samples = X.shape[0]
+        n_features = self.n_estimators * self.max_samples_
+
+        rows = np.tile(np.arange(n_samples), self.n_estimators)
+        cols = np.empty(n_samples * self.n_estimators, dtype=np.int32)
+        data = np.ones(n_samples * self.n_estimators, dtype=np.float64)
+
+        for est_idx, (tree, leaf_index) in enumerate(
+            zip(self.trees_, self.leaf_indices_, strict=True)
+        ):
+            cells = leaf_index[tree.apply(X)]
+            start_idx = est_idx * n_samples
+            end_idx = (est_idx + 1) * n_samples
+            cols[start_idx:end_idx] = cells + (est_idx * self.max_samples_)
+
+        return sparse.csr_matrix((data, (rows, cols)), shape=(n_samples, n_features))

ikpykit/kernel/_ik_inne.py

@@ -29,11 +29,14 @@ class IK_INNE(TransformerMixin, BaseEstimator):
     the characteristics of the local data distribution. It has been shown promising
     performance on density and distance-based classification and clustering problems.
 
-    This version uses iforest to split the data space and calculate Isolation
-    kernel Similarity. Based on this implementation, the feature
-    in the Isolation kernel space is the index of the cell in Voronoi diagrams. Each
-    point is represented as a binary vector such that only the cell the point falling
-    into is 1.
+    This version splits the data space with hyperspheres: each estimator draws
+    `max_samples` points and puts a ball around every one of them, reaching out
+    to that point's nearest neighbour among the draw. The cells are therefore
+    balls, where `anne` has Voronoi cells and `iforest` has axis-parallel boxes.
+    The feature in the Isolation kernel space is the index of the ball a point
+    falls into, so each point is represented as a binary vector such that only
+    the cell the point falling into is 1. A point outside every ball falls into
+    no cell and is represented by zeros.
 
     Parameters
     ----------
@@ -50,9 +53,13 @@ class IK_INNE(TransformerMixin, BaseEstimator):
 
     References
     ----------
-    .. [1] Qin, X., Ting, K.M., Zhu, Y. and Lee, V.C.
-    "Nearest-neighbour-induced isolation similarity and its impact on density-based clustering".
-    In Proceedings of the AAAI Conference on Artificial Intelligence, Vol. 33, 2019, July, pp. 4755-4762
+    1. Qin, X., Ting, K.M., Zhu, Y. and Lee, V.C.
+       "Nearest-neighbour-induced isolation similarity and its impact on density-based clustering".
+       In Proceedings of the AAAI Conference on Artificial Intelligence, Vol. 33, 2019, July, pp. 4755-4762
+
+    2. T. R. Bandaragoda, K. Ming Ting, D. Albrecht, F. T. Liu, Y. Zhu, and J. R. Wells.
+       "Isolation-based anomaly detection using nearest-neighbor ensembles." In Computational
+       Intelligence, vol. 34, 2018, pp. 968-998.
     """
 
     def __init__(self, n_estimators, max_samples, random_state=None):

ikpykit/kernel/_isodiskernel.py

@@ -50,10 +50,10 @@ class IsoDisKernel(BaseEstimator, TransformerMixin):
 
     References
     ----------
-    .. [1] Kai Ming Ting, Bi-Cun Xu, Takashi Washio, and Zhi-Hua Zhou. 2020.
-    "Isolation Distributional Kernel: A New Tool for Kernel based Anomaly Detection".
-    In Proceedings of the 26th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining (KDD '20).
-    Association for Computing Machinery, New York, NY, USA, 198-206.
+    1. Kai Ming Ting, Bi-Cun Xu, Takashi Washio, and Zhi-Hua Zhou. 2020.
+       "Isolation Distributional Kernel: A New Tool for Kernel based Anomaly Detection".
+       In Proceedings of the 26th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining (KDD '20).
+       Association for Computing Machinery, New York, NY, USA, 198-206.
 
     Examples
     --------