oodeel 0.4.0__py3-none-any.whl

oodeel/methods/dknn.py

@@ -0,0 +1,185 @@
+# -*- coding: utf-8 -*-
+# Copyright IRT Antoine de Saint Exupéry et Université Paul Sabatier Toulouse III - All
+# rights reserved. DEEL is a research program operated by IVADO, IRT Saint Exupéry,
+# CRIAQ and ANITI - https://www.deel.ai/
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+import faiss
+import numpy as np
+
+from ..aggregator import BaseAggregator
+from ..types import TensorType
+from .base import FeatureBasedDetector
+
+
+class DKNN(FeatureBasedDetector):
+    """
+    "Out-of-Distribution Detection with Deep Nearest Neighbors"
+    https://arxiv.org/abs/2204.06507
+
+    Args:
+        nearest: number of nearest neighbors to consider.
+            Defaults to 50.
+        use_gpu (bool): Whether to enable GPU acceleration for FAISS. Defaults to False.
+        aggregator (Optional[BaseAggregator]): Aggregator to combine scores from
+            multiple feature layers. If not provided and multiple layers are used, a
+            StdNormalizedAggregator will be employed.
+        **kwargs: Additional keyword arguments for the base class.
+    """
+
+    def __init__(
+        self,
+        nearest: int = 50,
+        use_gpu: bool = False,
+        aggregator: BaseAggregator = None,
+        **kwargs,
+    ):
+        super().__init__(aggregator=aggregator, **kwargs)
+        self.nearest = nearest
+        self.use_gpu = use_gpu
+        self.indexes: list[faiss.IndexFlatL2] = []
+
+        if self.use_gpu:
+            try:
+                self.res = faiss.StandardGpuResources()
+            except AttributeError as e:
+                raise ImportError(
+                    "faiss-gpu is not installed, but use_gpu was set to True."
+                    + "Please install faiss-gpu or set use_gpu to False."
+                ) from e
+
+    # === Per-layer logic ===
+    def _fit_layer(
+        self,
+        layer_id: int,
+        layer_features: np.ndarray,
+        info: dict,
+        **kwargs,
+    ) -> None:
+        """Fit one FAISS index for a single layer.
+
+        The extracted features are L2-normalized and stored into a FAISS index
+        dedicated to the current layer. Aggregator scores, if needed, are
+        computed separately via :func:`_score_layer` with `fit=True`.
+
+        Args:
+            layer_id: Index of the processed layer.
+            layer_features: Feature tensor corresponding to that layer.
+            info: Dictionary of auxiliary data (unused).
+        """
+        norm_features = self._prepare_layer_features(layer_features)
+        index = self._create_index(norm_features.shape[1])
+        index.add(norm_features)
+
+        self.indexes.append(index)
+
+    def _score_layer(
+        self,
+        layer_id: int,
+        layer_features: TensorType,
+        info: dict,
+        fit: bool = False,
+        **kwargs,
+    ) -> np.ndarray:
+        """Compute KNN scores for a single feature layer.
+
+        Args:
+            layer_id: Index of the processed layer.
+            layer_features: Feature tensor associated with this layer.
+            info: Dictionary of auxiliary data (unused).
+            fit: If `True`, scoring is performed as part of the fitting routine (for
+                the aggregator) and uses `max(nearest, 2)` neighbours. This avoids the
+                trivial zero distance obtained when `nearest` equals one. In inference
+                mode (`fit=False`), `nearest` neighbours are used.
+
+        Returns:
+            np.ndarray: Distance to the :math:`k`-th nearest neighbour.
+        """
+        index = self.indexes[layer_id]
+        layer_features = self.op.convert_to_numpy(layer_features)
+        norm_features = self._prepare_layer_features(layer_features)
+        k = max(self.nearest, 2) if fit else self.nearest
+        scores, _ = index.search(norm_features, k)
+        return scores[:, -1]
+
+    # === Internal utilities ===
+    def _prepare_layer_features(self, features: np.ndarray) -> np.ndarray:
+        """
+        Convert a feature tensor to a 2D numpy array and apply L2 normalization.
+
+        Args:
+            features (np.ndarray): Feature tensor to be processed.
+
+        Returns:
+            np.ndarray: Processed feature array with shape (num_samples, feature_dim)
+                and L2 normalized.
+        """
+        features = features.reshape(features.shape[0], -1)
+        return self._l2_normalization(features)
+
+    def _create_index(self, dim: int) -> faiss.IndexFlatL2:
+        """
+        Create a FAISS index for features of a given dimensionality.
+
+        Args:
+            dim (int): Dimensionality of the feature vectors.
+
+        Returns:
+            faiss.IndexFlatL2: A FAISS index instance, using GPU acceleration if
+                enabled.
+        """
+        if self.use_gpu:
+            cpu_index = faiss.IndexFlatL2(dim)
+            return faiss.index_cpu_to_gpu(self.res, 0, cpu_index)
+        else:
+            return faiss.IndexFlatL2(dim)
+
+    def _l2_normalization(self, feat: np.ndarray) -> np.ndarray:
+        """
+        Apply L2 normalization to an array of feature vectors along the last dimension.
+
+        Args:
+            feat (np.ndarray): Input array of features.
+
+        Returns:
+            np.ndarray: L2-normalized feature array.
+        """
+        return feat / (np.linalg.norm(feat, ord=2, axis=-1, keepdims=True) + 1e-10)
+
+    # === Properties ===
+    @property
+    def requires_to_fit_dataset(self) -> bool:
+        """
+        Whether an OOD detector needs a `fit_dataset` argument in the fit function.
+
+        Returns:
+            bool: True if `fit_dataset` is required else False.
+        """
+        return True
+
+    @property
+    def requires_internal_features(self) -> bool:
+        """
+        Whether an OOD detector acts on internal model features.
+
+        Returns:
+            bool: True if the detector perform computations on an intermediate layer
+            else False.
+        """
+        return True

oodeel/methods/energy.py

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+# Copyright IRT Antoine de Saint Exupéry et Université Paul Sabatier Toulouse III - All
+# rights reserved. DEEL is a research program operated by IVADO, IRT Saint Exupéry,
+# CRIAQ and ANITI - https://www.deel.ai/
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+import numpy as np
+from scipy.special import logsumexp
+
+from ..types import TensorType
+from ..types import Tuple
+from .base import OODBaseDetector
+
+
+class Energy(OODBaseDetector):
+    r"""
+    Energy Score method for OOD detection.
+    "Energy-based Out-of-distribution Detection"
+    https://arxiv.org/abs/2010.03759
+
+    This method assumes that the model has been trained with cross entropy loss
+    $CE(model(x))$ where $model(x)=(l_{c})_{c=1}^{C}$ are the logits
+    predicted for input $x$.
+    The implementation assumes that the logits are retreieved using the output with
+    linear activation.
+
+    The energy score for input $x$ is given by
+    $$ -\log \sum_{c=0}^C \exp(l_c)$$
+
+    where $model(x)=(l_{c})_{c=1}^{C}$ are the logits predicted by the model on
+    $x$.
+    As always, training data is expected to have lower score than OOD data.
+
+    Args:
+        use_react (bool): if true, apply ReAct method by clipping penultimate
+            activations under a threshold value.
+        react_quantile (Optional[float]): q value in the range [0, 1] used to compute
+            the react clipping threshold defined as the q-th quantile penultimate layer
+            activations. Defaults to 0.8.
+    """
+
+    def __init__(
+        self,
+        use_react: bool = False,
+        use_scale: bool = False,
+        use_ash: bool = False,
+        react_quantile: float = 0.8,
+        scale_percentile: float = 0.85,
+        ash_percentile: float = 0.90,
+        **kwargs,
+    ):
+        super().__init__(
+            use_react=use_react,
+            use_scale=use_scale,
+            use_ash=use_ash,
+            react_quantile=react_quantile,
+            scale_percentile=scale_percentile,
+            ash_percentile=ash_percentile,
+            **kwargs,
+        )
+
+    def _score_tensor(self, inputs: TensorType) -> Tuple[np.ndarray]:
+        """
+        Computes an OOD score for input samples "inputs" based on
+        energy, namey $-logsumexp(logits(inputs))$.
+
+        Args:
+            inputs: input samples to score
+
+        Returns:
+            Tuple[np.ndarray]: scores, logits
+        """
+        # optional: apply input perturbation
+        if self.eps > 0:
+            inputs = self._input_perturbation(inputs, self.eps, self.temperature)
+
+        # compute logits (softmax(logits,axis=1) is the actual softmax
+        # output minimized using binary cross entropy)
+        _, logits = self.feature_extractor.predict_tensor(inputs)
+        logits = self.op.convert_to_numpy(logits)
+        scores = -logsumexp(logits, axis=1)
+        return scores
+
+    @property
+    def requires_to_fit_dataset(self) -> bool:
+        """
+        Whether an OOD detector needs a `fit_dataset` argument in the fit function.
+
+        Returns:
+            bool: True if `fit_dataset` is required else False.
+        """
+        return False
+
+    @property
+    def requires_internal_features(self) -> bool:
+        """
+        Whether an OOD detector acts on internal model features.
+
+        Returns:
+            bool: True if the detector perform computations on an intermediate layer
+            else False.
+        """
+        return False

oodeel/methods/entropy.py

@@ -0,0 +1,113 @@
+# -*- coding: utf-8 -*-
+# Copyright IRT Antoine de Saint Exupéry et Université Paul Sabatier Toulouse III - All
+# rights reserved. DEEL is a research program operated by IVADO, IRT Saint Exupéry,
+# CRIAQ and ANITI - https://www.deel.ai/
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+import numpy as np
+
+from ..types import TensorType
+from ..types import Tuple
+from .base import OODBaseDetector
+
+
+class Entropy(OODBaseDetector):
+    r"""
+    Entropy OOD score
+
+
+    The method consists in using the Entropy of the input data computed using the
+    Entropy $\sum_{c=0}^C p(y=c| x) \times log(p(y=c | x))$ where
+    $p(y=c| x) = \text{model}(x)$.
+
+    **Reference**
+    https://proceedings.neurips.cc/paper/2019/hash/1e79596878b2320cac26dd792a6c51c9-Abstract.html,
+    Neurips 2019.
+
+    Args:
+        use_react (bool): if true, apply ReAct method by clipping penultimate
+            activations under a threshold value.
+        react_quantile (Optional[float]): q value in the range [0, 1] used to compute
+            the react clipping threshold defined as the q-th quantile penultimate layer
+            activations. Defaults to 0.8.
+    """
+
+    def __init__(
+        self,
+        use_react: bool = False,
+        use_scale: bool = False,
+        use_ash: bool = False,
+        react_quantile: float = 0.8,
+        scale_percentile: float = 0.85,
+        ash_percentile: float = 0.90,
+        **kwargs,
+    ):
+        super().__init__(
+            use_react=use_react,
+            use_scale=use_scale,
+            use_ash=use_ash,
+            react_quantile=react_quantile,
+            scale_percentile=scale_percentile,
+            ash_percentile=ash_percentile,
+            **kwargs,
+        )
+
+    def _score_tensor(self, inputs: TensorType) -> Tuple[np.ndarray]:
+        """
+        Computes an OOD score for input samples "inputs" based on
+        entropy.
+
+        Args:
+            inputs: input samples to score
+
+        Returns:
+            Tuple[np.ndarray]: scores, logits
+        """
+        # optional: apply input perturbation
+        if self.eps > 0:
+            inputs = self._input_perturbation(inputs, self.eps, self.temperature)
+
+        # compute logits (softmax(logits,axis=1) is the actual softmax
+        # output minimized using binary cross entropy)
+        _, logits = self.feature_extractor.predict_tensor(inputs)
+        probits = self.op.softmax(logits)
+        probits = self.op.convert_to_numpy(probits)
+        scores = np.sum(probits * np.log(probits), axis=1)
+        return -scores
+
+    @property
+    def requires_to_fit_dataset(self) -> bool:
+        """
+        Whether an OOD detector needs a `fit_dataset` argument in the fit function.
+
+        Returns:
+            bool: True if `fit_dataset` is required else False.
+        """
+        return False
+
+    @property
+    def requires_internal_features(self) -> bool:
+        """
+        Whether an OOD detector acts on internal model features.
+
+        Returns:
+            bool: True if the detector perform computations on an intermediate layer
+            else False.
+        """
+        return False

oodeel/methods/gen.py

@@ -0,0 +1,113 @@
+# -*- coding: utf-8 -*-
+# Copyright IRT Antoine de Saint Exupéry et Université Paul Sabatier Toulouse III - All
+# rights reserved. DEEL is a research program operated by IVADO, IRT Saint Exupéry,
+# CRIAQ and ANITI - https://www.deel.ai/
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+import numpy as np
+
+from ..types import TensorType
+from ..types import Tuple
+from .base import OODBaseDetector
+
+
+class GEN(OODBaseDetector):
+    """
+    Generalized Entropy method for OOD detection.
+    "GEN: Pushing the Limits of Softmax-Based Out-of-Distribution Detection"
+    https://openaccess.thecvf.com/content/CVPR2023/html/Liu_GEN_Pushing_the_Limits_of_Softmax-Based_Out-of-Distribution_Detection_CVPR_2023_paper.html,
+
+    Args:
+        gamma (float): parameter for the generalized entropy. Must be between 0 and 1.
+            Defaults to 0.1.
+        k (int): number of softmax values to keep for the entropy computation. Only the
+            top-k softmax probabilities will be used. Defaults to 100.
+        use_react (bool): if true, apply ReAct method by clipping penultimate
+            activations under a threshold value.
+        react_quantile (Optional[float]): q value in the range [0, 1] used to compute
+            the react clipping threshold defined as the q-th quantile penultimate layer
+            activations. Defaults to 0.8.
+    """
+
+    def __init__(
+        self,
+        gamma: float = 0.1,
+        k: int = 100,
+        use_react: bool = False,
+        use_scale: bool = False,
+        use_ash: bool = False,
+        react_quantile: float = 0.8,
+        scale_percentile: float = 0.85,
+        ash_percentile: float = 0.90,
+        **kwargs,
+    ):
+        super().__init__(
+            use_react=use_react,
+            use_scale=use_scale,
+            use_ash=use_ash,
+            react_quantile=react_quantile,
+            scale_percentile=scale_percentile,
+            ash_percentile=ash_percentile,
+            **kwargs,
+        )
+        self.gamma = gamma
+        self.k = k
+
+    def _score_tensor(self, inputs: TensorType) -> Tuple[np.ndarray]:
+        """
+        Computes an OOD score for input samples "inputs" based on
+        the distance to nearest neighbors in the feature space of self.model
+
+        Args:
+            inputs: input samples to score
+
+        Returns:
+            Tuple[np.ndarray]: scores, logits
+        """
+        # optional: apply input perturbation
+        if self.eps > 0:
+            inputs = self._input_perturbation(inputs, self.eps, self.temperature)
+
+        _, logits = self.feature_extractor.predict_tensor(inputs)
+        probs = self.op.softmax(logits)
+        probs = self.op.convert_to_numpy(probs)
+        probs = np.sort(probs)[:, -self.k :]  # Keep the k largest probabilities
+        scores = np.sum(probs**self.gamma * (1 - probs) ** (self.gamma), axis=-1)
+        return scores
+
+    @property
+    def requires_to_fit_dataset(self) -> bool:
+        """
+        Whether an OOD detector needs a `fit_dataset` argument in the fit function.
+
+        Returns:
+            bool: True if `fit_dataset` is required else False.
+        """
+        return False
+
+    @property
+    def requires_internal_features(self) -> bool:
+        """
+        Whether an OOD detector acts on internal model features.
+
+        Returns:
+            bool: True if the detector perform computations on an intermediate layer
+            else False.
+        """
+        return False