Add Deep SAD (Deep Semi-Supervised Anomaly Detection) detector

README.rst

@@ -71,7 +71,7 @@ PyOD 3 is the most comprehensive Python library for anomaly detection. Four pill
 ===========================  ========================================================================================
 Pillar                       What it means
 ===========================  ========================================================================================
-Multi-Modal                  61 detectors across **tabular, time series, graph, text, image, and audio** data, one API
+Multi-Modal                  62 detectors across **tabular, time series, graph, text, image, and audio** data, one API
 Full Lifecycle               From raw data to explained anomalies and next-step guidance in a single call
 Agentic                      ``od-expert`` turns natural-language requests into ADEngine workflows; MCP exposes structured tools for other agents
 Most Used                    46+ million downloads; benchmark-backed routing (ADBench, TSB-AD, BOND, NLP-ADBench)
@@ -485,6 +485,11 @@ PyOD is organized into two functional groups: **(i) Detection Algorithms**, with
      - Deep One-Class Classification (`example <https://github.com/yzhao062/pyod/blob/development/examples/deepsvdd_example.py>`__)
      - 2018
      - [#Ruff2018Deep]_
+   * - Neural Networks
+     - DeepSAD
+     - Deep Semi-Supervised Anomaly Detection (`example <https://github.com/yzhao062/pyod/blob/development/examples/deep_sad_example.py>`__)
+     - 2020
+     - [#Ruff2020Deep]_
    * - Neural Networks
      - AnoGAN
      - Anomaly Detection with Generative Adversarial Networks
@@ -896,6 +901,8 @@ Reference
 
 .. [#Ruff2018Deep] Ruff, L., Vandermeulen, R., Goernitz, N., Deecke, L., Siddiqui, S.A., Binder, A., Müller, E. and Kloft, M., 2018, July. Deep one-class classification. In *International conference on machine learning* (pp. 4393-4402). PMLR.
 
+.. [#Ruff2020Deep] Ruff, L., Vandermeulen, R.A., Görnitz, N., Binder, A., Müller, E., Müller, K.R. and Kloft, M., 2020. Deep semi-supervised anomaly detection. In *International Conference on Learning Representations (ICLR)*.
+
 .. [#Schlegl2017Unsupervised] Schlegl, T., Seeböck, P., Waldstein, S.M., Schmidt-Erfurth, U. and Langs, G., 2017, June. Unsupervised anomaly detection with generative adversarial networks to guide marker discovery. In International conference on information processing in medical imaging (pp. 146-157). Springer, Cham.
 
 .. [#Scholkopf2001Estimating] Scholkopf, B., Platt, J.C., Shawe-Taylor, J., Smola, A.J. and Williamson, R.C., 2001. Estimating the support of a high-dimensional distribution. *Neural Computation*, 13(7), pp.1443-1471.

docs/examples/tabular.rst

@@ -1,7 +1,7 @@
 Layer 1: Tabular Anomaly Detection
 ====================================
 
-PyOD has 43 tabular detectors covering probabilistic, linear, proximity, ensemble, and deep learning approaches. All use the same ``fit``/``predict``/``decision_function`` API.
+PyOD has 44 tabular detectors covering probabilistic, linear, proximity, ensemble, and deep learning approaches. All use the same ``fit``/``predict``/``decision_function`` API.
 
 .. code-block:: python
 

docs/index.rst

@@ -71,7 +71,7 @@ PyOD 3 is the most comprehensive Python library for anomaly detection. Four pill
 ===========================  ========================================================================================
 Pillar                       What it means
 ===========================  ========================================================================================
-Multi-Modal                  61 detectors across **tabular, time series, graph, text, image, and audio** data, one API
+Multi-Modal                  62 detectors across **tabular, time series, graph, text, image, and audio** data, one API
 Full Lifecycle               From raw data to explained anomalies and next-step guidance in a single call
 Agentic                      Ask in plain English, and AI agents run the full detection workflow without OD expertise
 Most Used                    `46+ million downloads <https://pepy.tech/project/pyod>`_; benchmark-backed routing (ADBench, TSB-AD, BOND, NLP-ADBench)
@@ -257,6 +257,7 @@ Neural Networks      Beta-VAE          Variational AutoEncoder (all customized l
 Neural Networks      SO_GAAL           Single-Objective Generative Adversarial Active Learning                                                 2019   :class:`pyod.models.so_gaal.SO_GAAL`                 :cite:`a-liu2019generative`
 Neural Networks      MO_GAAL           Multiple-Objective Generative Adversarial Active Learning                                               2019   :class:`pyod.models.mo_gaal.MO_GAAL`                 :cite:`a-liu2019generative`
 Neural Networks      DeepSVDD          Deep One-Class Classification                                                                           2018   :class:`pyod.models.deep_svdd.DeepSVDD`              :cite:`a-ruff2018deepsvdd`
+Neural Networks      DeepSAD           Deep Semi-Supervised Anomaly Detection                                                                  2020   :class:`pyod.models.deep_sad.DeepSAD`                :cite:`a-ruff2020deepsad`
 Neural Networks      AnoGAN            Anomaly Detection with Generative Adversarial Networks                                                  2017   :class:`pyod.models.anogan.AnoGAN`                   :cite:`a-schlegl2017unsupervised`
 Neural Networks      ALAD              Adversarially learned anomaly detection                                                                 2018   :class:`pyod.models.alad.ALAD`                       :cite:`a-zenati2018adversarially`
 Neural Networks      DevNet            Deep Anomaly Detection with Deviation Networks                                                          2019   :class:`pyod.models.devnet.DevNet`                   :cite:`a-pang2019deep`

docs/install.rst

@@ -117,7 +117,7 @@ Example output:
 .. code-block:: text
 
     PyOD version:          3.1.0
-    Detectors (ADEngine):  61 total (43 tabular, 7 time-series, 8 graph, 2 text, 2 image, 1 multimodal, 3 audio)
+    Detectors (ADEngine):  62 total (44 tabular, 7 time-series, 8 graph, 2 text, 2 image, 1 multimodal, 3 audio)
     Classic API:           OK
     ADEngine (Layer 2):    OK
     MCP extra:             OK (run: pyod mcp serve)

docs/pyod.models.tabular.rst

@@ -105,6 +105,16 @@ pyod.models.copod module
     :show-inheritance:
 
 
+pyod.models.deep\_sad module
+----------------------------
+
+.. automodule:: pyod.models.deep_sad
+    :members:
+    :exclude-members: InnerDeepSAD
+    :undoc-members:
+    :show-inheritance:
+
+
 pyod.models.deep\_svdd module
 -----------------------------
 

docs/zreferences.bib

@@ -369,6 +369,13 @@ @article{ruff2018deepsvdd
   year={2018}
 }
 
+@inproceedings{ruff2020deepsad,
+  title={Deep Semi-Supervised Anomaly Detection},
+  author={Ruff, Lukas and Vandermeulen, Robert A. and Görnitz, Nico and Binder, Alexander and Müller, Emmanuel and Müller, Klaus-Robert and Kloft, Marius},
+  booktitle={International Conference on Learning Representations},
+  year={2020}
+}
+
 @article{birge2006many,
   title={How many bins should be put in a regular histogram},
   author={Birg{\'e}, Lucien and Rozenholc, Yves},

examples/agentic_example.py

@@ -2,7 +2,7 @@
 """Example: Agent-driven anomaly detection with PyOD 3 (Layer 3).
 
 Demonstrates what makes PyOD distinctive in the agentic workflow:
-    - 61 detectors across 6 data modalities
+    - 62 detectors across 6 data modalities
     - Benchmark-backed detector selection (ADBench, TSB-AD, BOND)
     - Multi-detector consensus with per-detector scores
     - Result quality assessment

examples/deep_sad_example.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+"""Example of using Deep SAD for semi-supervised outlier detection
+"""
+# Author: Jayesh Suryavanshi <jayeshksuryavanshi@gmail.com>
+# License: BSD 2 clause
+
+from __future__ import division
+from __future__ import print_function
+
+import os
+import sys
+
+import numpy as np
+
+# temporary solution for relative imports in case pyod is not installed
+# if pyod is installed, no need to use the following line
+sys.path.append(
+    os.path.abspath(os.path.join(os.path.dirname("__file__"), '..')))
+
+from pyod.models.deep_sad import DeepSAD
+from pyod.utils.data import generate_data
+from pyod.utils.data import evaluate_print
+
+if __name__ == "__main__":
+    contamination = 0.1  # percentage of outliers
+    n_train = 20000  # number of training points
+    n_test = 2000  # number of testing points
+    n_features = 300  # number of features
+    random_state = 10  # if c is set to None use random_state
+
+    # Generate sample data
+    X_train, X_test, y_train, y_test = \
+        generate_data(n_train=n_train,
+                      n_test=n_test,
+                      n_features=n_features,
+                      contamination=contamination,
+                      random_state=42)
+
+    # Deep SAD is semi-supervised: reveal a fraction of the training
+    # anomalies as labeled (1) and keep the rest unlabeled (0).
+    semi_y = np.zeros(n_train, dtype=int)
+    anomaly_idx = np.where(y_train == 1)[0]
+    revealed = anomaly_idx[:len(anomaly_idx) // 2]
+    semi_y[revealed] = 1
+
+    # train Deep SAD detector
+    clf_name = 'DeepSAD'
+    clf = DeepSAD(n_features=n_features, epochs=5,
+                  contamination=contamination, random_state=random_state)
+    clf.fit(X_train, semi_y)
+
+    # get the prediction labels and outlier scores of the training data
+    y_train_pred = clf.labels_  # binary labels (0: inliers, 1: outliers)
+    y_train_scores = clf.decision_scores_  # raw outlier scores
+
+    # get the prediction on the test data
+    y_test_pred = clf.predict(X_test)  # outlier labels (0 or 1)
+    y_test_scores = clf.decision_function(X_test)  # outlier scores
+
+    # evaluate and print the results
+    print("\nOn Training Data:")
+    evaluate_print(clf_name, y_train, y_train_scores)
+    print("\nOn Test Data:")
+    evaluate_print(clf_name, y_test, y_test_scores)