Merge pull request #727 from yzhao062/development

v3.6.5: contributor bug fixes plus review follow-ups

Author: yzhao062

CHANGES.txt

@@ -92,10 +92,15 @@ class CBLOF(BaseDetector):
         RandomState instance used by `np.random`.
 
     n_jobs : int, optional (default=1)
-        Accepted for API compatibility but currently unused: the value is
-        neither stored on the estimator nor forwarded to the clustering
-        step, so ``get_params()`` reports ``None`` for it and ``clone()``
-        does not carry it over. See issue #713.
+        Deprecated compatibility parameter. ``KMeans.n_jobs`` was deprecated
+        in scikit-learn 0.23 and removed in 1.0, so this value is stored for
+        ``get_params()`` / ``clone()`` compatibility but is not forwarded.
+        Values other than 1 emit a ``FutureWarning`` during ``fit()`` and
+        support will be removed in PyOD v4.0.0. Control the default KMeans
+        parallelism with the
+        ``OMP_NUM_THREADS`` environment variable or ``threadpoolctl``. For a
+        custom ``clustering_estimator``, configure parallelism on that
+        estimator directly.
 
     Attributes
     ----------
@@ -149,6 +154,7 @@ def __init__(self, n_clusters=8, contamination=0.1,
         self.use_weights = use_weights
         self.check_estimator = check_estimator
         self.random_state = random_state
+        self.n_jobs = n_jobs
 
     # noinspection PyIncorrectDocstring
     def fit(self, X, y=None):
@@ -168,6 +174,16 @@ def fit(self, X, y=None):
             Fitted estimator.
         """
 
+        if self.n_jobs != 1:
+            warnings.warn(
+                "The 'n_jobs' parameter is deprecated and will be removed "
+                "in PyOD v4.0.0. It has no effect on the default KMeans "
+                "estimator. Control KMeans parallelism with the "
+                "OMP_NUM_THREADS environment variable or threadpoolctl, or "
+                "configure parallelism on a custom clustering_estimator.",
+                FutureWarning,
+                stacklevel=2)
+
         # validate inputs X and y (optional)
         X = check_array(X)
         self._set_n_classes(y)
@@ -176,8 +192,7 @@ def fit(self, X, y=None):
         # check parameters
         # number of clusters are default to 8
         self._validate_estimator(default=KMeans(
-            n_clusters=self.n_clusters,
-            random_state=self.random_state))
+            n_clusters=self.n_clusters, random_state=self.random_state))
 
         self.clustering_estimator_.fit(X=X, y=y)
         # Get the labels of the clustering results

pyod/models/cblof.py

@@ -6,6 +6,7 @@
 
 
 import multiprocessing
+import warnings
 from itertools import combinations as com
 from multiprocessing import Pool
 
@@ -182,15 +183,24 @@ def rod_3D(x, gm=None, median=None, scaler1=None, scaler2=None):
 
     Parameters
     ----------
-    x : array-like, 3D data points.
+    x : array-like of shape (n_samples, 3), n_samples >= 1
+        3D data points. A zero-row input raises from ``geometric_median``.
     gm: list (default=None), the geometric median
     median: float (default=None), MAD median
     scaler1: obj (default=None), MinMaxScaler of Angles group 1
     scaler2: obj (default=None), MinMaxScaler of Angles group 2
 
     Returns
     -------
-    decision_scores, gm, scaler1, scaler2
+    decision_scores, gm, median, scaler1, scaler2
+
+    Warns
+    -----
+    RuntimeWarning
+        When the geometric median falls on the coordinate origin, no rotation
+        angle is defined for any row. The subspace then uses one constant
+        angle, so its costs are driven only by the distance from the geometric
+        median.
     """
     # find the geometric median if it is not already fit
     gm = geometric_median(x) if gm is None else gm
@@ -199,11 +209,48 @@ def rod_3D(x, gm=None, median=None, scaler1=None, scaler2=None):
     _x = x - gm
     # calculate the scaled angles between the geometric median and each data point vector
     v_norm = np.linalg.norm(_x, axis=1)
-    gammas, scaler1, scaler2 = scale_angles(
-        np.arccos(np.clip(np.dot(_x, gm) / (v_norm * norm_), -1, 1)),
-        scaler1=scaler1, scaler2=scaler2)
-    # apply the ROD main equation to find the rotation costs
-    costs = np.power(v_norm, 3) * np.cos(gammas) * np.square(np.sin(gammas))
+    if norm_ == 0:
+        warnings.warn(
+            "The geometric median is at the coordinate origin "
+            "(norm_ == 0), so no rotation angle is defined for this ROD "
+            "subspace. Its scores fall back to being driven only by the "
+            "distance from the geometric median.",
+            RuntimeWarning, stacklevel=2)
+        # There is no reference direction, so use one constant angle for the
+        # whole subspace. Its trigonometric factor is then constant, reducing
+        # the rotation cost to a constant times v_norm**3. Note that MAD still
+        # scores each row by how far its cost sits from the median cost, so
+        # the result is not a plain ordering by distance.
+        # Size from v_norm, not x: this helper documents x as array-like and a
+        # plain list works on the ordinary path, because x - gm broadcasts
+        # through gm. Reading x.shape here would break list callers on exactly
+        # the degenerate inputs these branches exist to serve.
+        gammas, scaler1, scaler2 = scale_angles(
+            np.full(v_norm.shape[0], np.pi / 2.),
+            scaler1=scaler1, scaler2=scaler2)
+        costs = (np.power(v_norm, 3) * np.cos(gammas) *
+                 np.square(np.sin(gammas)))
+    else:
+        denominator = v_norm * norm_
+        valid = denominator > 0
+        if np.all(valid):
+            # Preserve the original array-wide operations for ordinary data.
+            gammas, scaler1, scaler2 = scale_angles(
+                np.arccos(np.clip(np.dot(_x, gm) / denominator, -1, 1)),
+                scaler1=scaler1, scaler2=scaler2)
+            costs = (np.power(v_norm, 3) * np.cos(gammas) *
+                     np.square(np.sin(gammas)))
+        else:
+            gammas, scaler1, scaler2 = scale_angles(
+                np.arccos(np.clip(
+                    np.dot(_x[valid], gm) / denominator[valid], -1, 1)),
+                scaler1=scaler1, scaler2=scaler2)
+            # A zero-radius row has no displacement direction. Exclude its
+            # undefined angle from scaler fitting and assign its limiting
+            # cost 0.
+            costs = np.zeros(v_norm.shape[0])
+            costs[valid] = (np.power(v_norm[valid], 3) * np.cos(gammas) *
+                            np.square(np.sin(gammas)))
     # apply MAD to calculate the decision scores
     decision_scores, median = mad(costs, median=median)
     return decision_scores, list(gm), median, scaler1, scaler2

pyod/models/rod.py

@@ -1,7 +1,10 @@
 """Pytest configuration for PyOD tests.
 
 Conditional collection skip for torch-dependent test modules when
-torch is not installed.
+torch is absent, or when it is installed but fails to import in a
+local run. Under CI a broken install re-raises instead, so a job that
+promised full torch coverage cannot pass green while silently
+skipping all of it.
 
 Rationale: on macOS CI we deliberately do NOT install PyTorch because
 of the upstream NNPACK slowdown on Apple Silicon
@@ -25,11 +28,37 @@
 fixed PyTorch wheel is released.
 """
 
+import os
+import warnings
+
 collect_ignore_glob = []
 
 try:
     import torch  # noqa: F401
-except ImportError:
+except (ImportError, OSError) as _torch_exc:
+    # Absence and breakage are different states and must not be conflated.
+    # Only a top-level ModuleNotFoundError for "torch" proves the package is
+    # not installed; a broken install raises OSError (on Windows a partially
+    # installed wheel fails with "[WinError 127] ... shm.dll") or a plain
+    # ImportError from inside torch._C. Catching only ImportError used to abort
+    # collection of the entire suite rather than skipping the torch-dependent
+    # modules this guard exists to skip.
+    #
+    # Locally, a broken install degrades to a skip plus a loud warning. Under
+    # CI it re-raises: testing.yml and testing-cron.yml install the full
+    # dependency set on Linux and Windows and then run pytest with no torch
+    # preflight, so a silent skip there would let a job that promised full
+    # torch coverage pass green while running none of it.
+    _torch_absent = (isinstance(_torch_exc, ModuleNotFoundError)
+                     and _torch_exc.name == "torch")
+    if not _torch_absent:
+        if os.environ.get("CI") == "true":
+            raise
+        warnings.warn(
+            "torch is installed but failed to import ({!r}); skipping the "
+            "torch-dependent test modules.".format(_torch_exc),
+            RuntimeWarning,
+        )
     # Test modules that import torch (or torch_geometric) at module
     # load time. Keep this list in sync with torch-dependent tests.
     collect_ignore_glob = [

pyod/test/conftest.py

@@ -3,9 +3,11 @@
 import os
 import sys
 import unittest
+import warnings
 
 # noinspection PyProtectedMember
 from numpy.testing import assert_allclose
+from numpy.testing import assert_array_equal
 from numpy.testing import assert_array_less
 from numpy.testing import assert_equal
 from numpy.testing import assert_raises
@@ -166,6 +168,60 @@ def test_predict_rank_normalized(self):
     def test_model_clone(self):
         clone_clf = clone(self.clf)
 
+    def test_n_jobs_stored(self):
+        # n_jobs must be stored so get_params() and clone() carry it over
+        clf = CBLOF(n_jobs=4)
+        assert clf.n_jobs == 4
+        assert clf.get_params()['n_jobs'] == 4
+
+    def test_n_jobs_clone(self):
+        clf = CBLOF(n_jobs=4)
+        cloned = clone(clf)
+        assert cloned.n_jobs == 4
+
+    def test_n_jobs_fit(self):
+        # CBLOF(n_jobs=4) must fit and produce results identical to n_jobs=1
+        clf_single = CBLOF(contamination=self.contamination,
+                           random_state=42, n_jobs=1)
+        clf_multi = CBLOF(contamination=self.contamination,
+                          random_state=42, n_jobs=4)
+        clf_single.fit(self.X_train)
+        # Match the stable clause, not the removal version, so bumping the
+        # announced removal release does not require touching this test.
+        with self.assertWarnsRegex(
+                FutureWarning, r"'n_jobs' parameter is deprecated"):
+            clf_multi.fit(self.X_train)
+        assert clf_multi.n_jobs == 4
+        assert_equal(len(clf_multi.decision_scores_), self.X_train.shape[0])
+        # Exact, not allclose: CHANGES.txt claims bit identity, and n_jobs
+        # reaches nothing, so any drift at all would be a real defect.
+        assert_array_equal(clf_multi.decision_scores_,
+                           clf_single.decision_scores_)
+
+    def test_n_jobs_default_no_warning(self):
+        # Match only CBLOF's own message. Promoting every FutureWarning would
+        # turn an unrelated future scikit-learn deprecation surfacing from
+        # KMeans.fit into a red test whose failure names nothing about n_jobs.
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                'error', message="The 'n_jobs' parameter is deprecated",
+                category=FutureWarning)
+            clf = CBLOF(contamination=self.contamination,
+                        random_state=42, n_jobs=1)
+            clf.fit(self.X_train)
+
+    def test_n_jobs_init_does_not_warn(self):
+        # scikit-learn requires __init__ to only store its arguments, so the
+        # deprecation must come from fit(). Without this, moving the warn into
+        # __init__ leaves every other test green while breaking clone().
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                'error', message="The 'n_jobs' parameter is deprecated",
+                category=FutureWarning)
+            clf = CBLOF(contamination=self.contamination,
+                        random_state=42, n_jobs=4)
+            clone(clf)
+
     def tearDown(self):
         pass
 

pyod/test/test_cblof.py

@@ -10,6 +10,7 @@
 from numpy.testing import assert_allclose
 from numpy.testing import assert_equal
 from numpy.testing import assert_raises
+from sklearn.metrics import roc_auc_score
 
 # temporary solution for relative imports in case pyod is not installed
 # if pyod is installed, no need to use the following line
@@ -84,6 +85,105 @@ def test_data_generate3(self):
         assert_allclose(y_train, y_train2)
         assert_allclose(y_test, y_test2)
 
+    def test_data_generate_outliers_have_spread(self):
+        # Regression test for GH #141: for certain seeds the internal offset
+        # was drawn as 0, which collapsed every outlier onto the origin
+        # (uniform(-0, 0) == 0) and produced zero-variance outliers. Sweep a
+        # range of seeds (41, 48 and 50 previously triggered the collapse)
+        # and confirm outliers always keep a non-zero spread.
+        for seed in range(60):
+            X, y = generate_data(
+                n_features=2,
+                contamination=0.05,
+                train_only=True,
+                random_state=seed,
+            )
+            outliers = X[y == 1]
+            assert outliers.var(axis=0).min() > 0, \
+                "outliers collapsed to zero variance for random_state=%d" % seed
+
+    def test_data_generate_float_offset(self):
+        # A float offset in (1, 2) used to raise ValueError, because randint
+        # truncates its bounds and the redraw got low == high. It is now drawn
+        # continuously with a floor of 1.0. Assert separation, not merely a
+        # non-zero variance: a spread test alone would pass on data whose
+        # labelled outliers sit inside the inlier cloud.
+        for offset in (1.1, 1.5, np.nextafter(2.0, 1.0)):
+            with self.subTest(offset=offset):
+                for seed in range(5):
+                    X, y = generate_data(
+                        n_features=2,
+                        contamination=0.05,
+                        train_only=True,
+                        offset=offset,
+                        random_state=seed,
+                    )
+                    outliers = X[y == 1]
+                    assert outliers.var(axis=0).min() > 0
+                    centrality = np.linalg.norm(X - X.mean(axis=0), axis=1)
+                    assert roc_auc_score(y, centrality) > 0.7, \
+                        "outliers are not separated for offset=%r seed=%d" % (
+                            offset, seed)
+
+    def test_data_generate_redraw_branches_stable(self):
+        # The other golden test pins three default-offset seeds whose first
+        # draw is non-zero, so it exercises neither branch the GH #141 fix
+        # actually touches. Both seeds below take the zero-then-redraw path
+        # (the first randint returns 0): offset=1 hits the fixed offset_=1
+        # branch, and offset=2 hits the integer redraw.
+        #
+        # Pin an array-wide sum alongside the first and last rows, with a
+        # tolerance, rather than hashing the raw bytes. A byte-exact pin is
+        # not portable: randn draws Gaussians by the polar method, whose log
+        # is not required to be correctly rounded, so libm implementations
+        # disagree in the last ulp and the same seed yields different low bits
+        # on macOS than on Linux or Windows. The sum still covers every element,
+        # so an inserted or reordered RNG draw, which moves values by O(1),
+        # cannot hide inside this tolerance.
+        golden = {
+            (1, 0): (1888.646949950,
+                     [1.407737153, 1.853812935], [0.716955137, -0.505085628]),
+            (2, 0): (1907.119693504,
+                     [1.070368485, 1.067679162], [-0.467865797, 0.251365755]),
+        }
+        for (offset, seed), (total, first, last) in golden.items():
+            with self.subTest(offset=offset, seed=seed):
+                X, _ = generate_data(n_features=2, contamination=0.05,
+                                     train_only=True, offset=offset,
+                                     random_state=seed)[:2]
+                assert_equal(X.shape, (1000, 2))
+                assert_allclose(X.sum(), total, rtol=0, atol=1e-6)
+                assert_allclose(X[0], first, rtol=0, atol=1e-9)
+                assert_allclose(X[-1], last, rtol=0, atol=1e-9)
+
+    def test_data_generate_offset_below_one_rejected(self):
+        # An offset below 1 must keep raising. coef_, the inlier spread, is
+        # drawn from [0.001, 1.001) independently of offset, so an outlier box
+        # of half-width < 1 lands inside an O(1) inlier cloud and the labelled
+        # outliers become the densest points in the sample.
+        for offset in (0.01, 0.5, np.nextafter(1.0, 0.0)):
+            with self.subTest(offset=offset):
+                with self.assertRaises(ValueError):
+                    generate_data(train_only=True, offset=offset,
+                                  random_state=0)
+
+    def test_data_generate_reproducibility(self):
+        # Golden values pinned from the pre-fix implementation for seeds whose
+        # offset was already non-zero. Redrawing only when the offset comes out
+        # as 0 leaves these untouched, so this guards against a future change
+        # silently altering long-standing fixed-seed output.
+        golden = {
+            0: ([5.059894904, 5.061739412], [-0.263919547, 3.009107520]),
+            1: ([3.401186423, 3.524852969], [0.181525489, 3.650202520]),
+            42: ([6.433658544, 5.509168303], [-3.206743915, -4.912722786]),
+        }
+        for seed, (first, last) in golden.items():
+            X, _ = generate_data(n_train=10, n_test=5, n_features=2,
+                                 contamination=0.2, train_only=True,
+                                 random_state=seed)
+            assert_allclose(X[0], first, rtol=0, atol=1e-9)
+            assert_allclose(X[-1], last, rtol=0, atol=1e-9)
+
     def test_data_generate_cluster(self):
         X_train, X_test, y_train, y_test = \
             generate_data_clusters(n_train=self.n_train,