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

Merges #706 (generate_data zero-offset collapse, Mohit-Ak), #719 (CBLOF
n_jobs, bishtashish708) and #722 (ROD divide-by-zero, bishtashish708),
then fixes the defects a two-panel review and two rounds of Codex review
found in them.

- generate_data: redraw only a zero offset; accept float offsets in (1, 2);
  reject offset < 1 explicitly; coerce randint bounds with int()
- CBLOF: store n_jobs, never forward it to KMeans, deprecate it from fit()
- ROD: exclude undefined angles from the scaler fit; handle an origin
  geometric median explicitly; keep list input working on both paths
- conftest: a broken torch import skips torch modules locally and
  re-raises under CI instead of silently dropping 25 modules

Scores change only for inputs that were previously degenerate or NaN;
CHANGES.txt discloses every user-visible behavior change.

Author: yzhao062

CHANGES.txt

@@ -6,7 +6,6 @@
 # License: BSD 2 clause
 
 
-import inspect
 import warnings
 
 import numpy as np
@@ -93,14 +92,15 @@ class CBLOF(BaseDetector):
         RandomState instance used by `np.random`.
 
     n_jobs : int, optional (default=1)
-        Number of parallel jobs for the default KMeans backend.
-        Only forwarded to ``KMeans`` when set to a value other than 1
-        *and* the installed scikit-learn version supports it (the
-        parameter was deprecated in 0.23 and removed in 0.25).
-        On sklearn >= 0.25, or when left at the default of 1, this value
-        is stored for ``get_params()`` / ``clone()`` compatibility only.
-        Has no effect when a custom ``clustering_estimator`` is provided;
-        set ``n_jobs`` on that estimator directly.
+        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
     ----------
@@ -174,24 +174,25 @@ 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)
         n_samples, n_features = X.shape
 
         # check parameters
         # number of clusters are default to 8
-        _kmeans_kwargs = dict(
-            n_clusters=self.n_clusters, random_state=self.random_state)
-        # n_jobs was removed from KMeans in sklearn 0.25; on 0.23/0.24 it is
-        # deprecated and emits FutureWarning for any concrete value, including
-        # the default 1.  Only forward when the user explicitly requested more
-        # than one job so that plain CBLOF().fit(X) stays warning-free.
-        if (self.clustering_estimator is None
-                and self.n_jobs != 1
-                and "n_jobs" in inspect.signature(KMeans.__init__).parameters):
-            _kmeans_kwargs["n_jobs"] = self.n_jobs
-        self._validate_estimator(default=KMeans(**_kmeans_kwargs))
+        self._validate_estimator(default=KMeans(
+            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,19 +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)
-    # Avoid divide-by-zero when a point coincides with the geometric median
-    # (v_norm == 0) or the median is at the origin (norm_ == 0).
-    # In both cases the angle is undefined; treat it as π/2 so the rotation
-    # cost (v_norm³ · cos · sin²) collapses to 0 and does not contaminate MAD.
-    safe_denom = v_norm * norm_
-    cos_vals = np.where(safe_denom > 0,
-                        np.dot(_x, gm) / np.where(safe_denom > 0, safe_denom, 1.0),
-                        0.0)
-    gammas, scaler1, scaler2 = scale_angles(
-        np.arccos(np.clip(cos_vals, -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
@@ -184,9 +186,41 @@ def test_n_jobs_fit(self):
         clf_multi = CBLOF(contamination=self.contamination,
                           random_state=42, n_jobs=4)
         clf_single.fit(self.X_train)
-        clf_multi.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

@@ -1,6 +1,7 @@
 # -*- coding: utf-8 -*-
 
 
+import hashlib
 import os
 import sys
 import unittest
@@ -10,6 +11,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
@@ -98,9 +100,71 @@ def test_data_generate_outliers_have_spread(self):
                 random_state=seed,
             )
             outliers = X[y == 1]
-            assert outliers.var() > 0, \
+            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_bit_identical(self):
+        # The existing golden test pins three default-offset seeds whose first
+        # draw is non-zero, so it exercises neither branch this patch 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. Hash the whole array rather than
+        # comparing first and last rows with a tolerance, because the claim is
+        # bit identity, and an inserted RNG draw would otherwise slip through.
+        golden = {
+            (1, 0): '674149faa5f4c205',
+            (2, 0): 'd6fb10e1aba45e19',
+        }
+        for (offset, seed), digest 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]
+                # '<f8' is the canonical encoding for this pin: little-endian
+                # float64. ascontiguousarray alone normalizes layout but keeps
+                # native byte order, which would make the digest differ on a
+                # big-endian host and reject a correct build.
+                canonical = np.ascontiguousarray(X, dtype='<f8')
+                actual = hashlib.sha256(
+                    canonical.tobytes(order='C')).hexdigest()[:16]
+                assert actual == digest, (
+                    'generate_data(offset=%r, random_state=%r) changed: %s '
+                    '!= %s' % (offset, seed, actual, digest))
+
+    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