pyAgrum-nightly 2.2.1.9.dev202510261761405498__cp310-abi3-macosx_11_0_arm64.whl → 2.3.0.9.dev202510281761586496__cp310-abi3-macosx_11_0_arm64.whl

pyagrum/common.py

@@ -1,4 +1,4 @@
-__version__ = '2.2.1.9'
+__version__ = '2.3.0.9'
 __license__ = __doc__
 __project_url__ = 'https://agrum.org'
 __project_name__ = 'pyAgrum'

pyagrum/config.py

@@ -63,6 +63,7 @@ class PyAgrumConfiguration(metaclass=GumSingleton):
 
   Examples
   --------
+    >>> import pyagrum as gum
     >>> gum.config["dynamicBN", "default_graph_size"] = 10
     >>> gum.config["dynamicBN", "default_graph_size"]
     "10"

pyagrum/explain/_ComputationCausal.py

@@ -0,0 +1,75 @@
+############################################################################
+#   This file is part of the aGrUM/pyAgrum library.                        #
+#                                                                          #
+#   Copyright (c) 2005-2025 by                                             #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#                                                                          #
+#   The aGrUM/pyAgrum library is free software; you can redistribute it    #
+#   and/or modify it under the terms of either :                           #
+#                                                                          #
+#    - the GNU Lesser General Public License as published by               #
+#      the Free Software Foundation, either version 3 of the License,      #
+#      or (at your option) any later version,                              #
+#    - the MIT license (MIT),                                              #
+#    - or both in dual license, as here.                                   #
+#                                                                          #
+#   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    #
+#                                                                          #
+#   This aGrUM/pyAgrum library is distributed in the hope that it will be  #
+#   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          #
+#   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or 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.                                        #
+#                                                                          #
+#   See LICENCES for more details.                                         #
+#                                                                          #
+#   SPDX-FileCopyrightText: Copyright 2005-2025                            #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      #
+#                                                                          #
+#   Contact  : info_at_agrum_dot_org                                       #
+#   homepage : http://agrum.gitlab.io                                      #
+#   gitlab   : https://gitlab.com/agrumery/agrum                           #
+#                                                                          #
+############################################################################
+
+import pyagrum as gum
+
+# Calculations
+import numpy as np
+
+
+class CausalComputation:
+  @staticmethod
+  def _outOfCoalition(tau: list[int], inter: list[int]) -> list[int]:
+    # Returns the intersection of the parameter inter and the complement of the coalition tau.
+    return [i for i in inter if i not in tau]
+
+  @staticmethod
+  def _doCalculus(bn: gum.BayesNet, tau: list[int]) -> gum.BayesNet:
+    # Creates a new Bayesian Network by removing incoming arcs to the nodes in tau.
+    doNetTemplate = gum.BayesNet(bn)
+    for i in tau:
+      parents = doNetTemplate.parents(i)
+      for j in parents:
+        doNetTemplate.eraseArc(j, i)
+    return doNetTemplate
+
+  @staticmethod
+  def _chgCpt(doNetTemplate: gum.BayesNet, tau: list[int], alpha: list[int]) -> None:
+    # Changes the conditional probability tables (CPTs) of the nodes in tau to reflect the values in alpha.
+    for i, j in zip(tau, alpha):
+      doNetTemplate.cpt(i).fillWith(0.0)
+      doNetTemplate.cpt(i)[int(j)] = 1.0
+
+  @staticmethod
+  def _weight(evidces: dict[int, int], count: int, doLazy: gum.LazyPropagation) -> np.ndarray:
+    # Returns the evidces probability.
+    # The signature must be : Dict[int, int], int, **kwargs
+    doLazy.updateEvidence(evidces)
+    return doLazy.evidenceProbability() * count

pyagrum/explain/_ComputationConditional.py

@@ -0,0 +1,48 @@
+############################################################################
+#   This file is part of the aGrUM/pyAgrum library.                        #
+#                                                                          #
+#   Copyright (c) 2005-2025 by                                             #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#                                                                          #
+#   The aGrUM/pyAgrum library is free software; you can redistribute it    #
+#   and/or modify it under the terms of either :                           #
+#                                                                          #
+#    - the GNU Lesser General Public License as published by               #
+#      the Free Software Foundation, either version 3 of the License,      #
+#      or (at your option) any later version,                              #
+#    - the MIT license (MIT),                                              #
+#    - or both in dual license, as here.                                   #
+#                                                                          #
+#   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    #
+#                                                                          #
+#   This aGrUM/pyAgrum library is distributed in the hope that it will be  #
+#   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          #
+#   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or 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.                                        #
+#                                                                          #
+#   See LICENCES for more details.                                         #
+#                                                                          #
+#   SPDX-FileCopyrightText: Copyright 2005-2025                            #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      #
+#                                                                          #
+#   Contact  : info_at_agrum_dot_org                                       #
+#   homepage : http://agrum.gitlab.io                                      #
+#   gitlab   : https://gitlab.com/agrumery/agrum                           #
+#                                                                          #
+############################################################################
+
+import numpy as np
+
+
+class ConditionalComputation:
+  @staticmethod
+  def _weight(evidces: dict[int, int], count: int) -> np.ndarray:
+    # The signature must be : Dict[int, int], int, **kwargs
+    return count

pyagrum/explain/_ComputationMarginal.py

@@ -0,0 +1,48 @@
+############################################################################
+#   This file is part of the aGrUM/pyAgrum library.                        #
+#                                                                          #
+#   Copyright (c) 2005-2025 by                                             #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#                                                                          #
+#   The aGrUM/pyAgrum library is free software; you can redistribute it    #
+#   and/or modify it under the terms of either :                           #
+#                                                                          #
+#    - the GNU Lesser General Public License as published by               #
+#      the Free Software Foundation, either version 3 of the License,      #
+#      or (at your option) any later version,                              #
+#    - the MIT license (MIT),                                              #
+#    - or both in dual license, as here.                                   #
+#                                                                          #
+#   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    #
+#                                                                          #
+#   This aGrUM/pyAgrum library is distributed in the hope that it will be  #
+#   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          #
+#   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or 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.                                        #
+#                                                                          #
+#   See LICENCES for more details.                                         #
+#                                                                          #
+#   SPDX-FileCopyrightText: Copyright 2005-2025                            #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      #
+#                                                                          #
+#   Contact  : info_at_agrum_dot_org                                       #
+#   homepage : http://agrum.gitlab.io                                      #
+#   gitlab   : https://gitlab.com/agrumery/agrum                           #
+#                                                                          #
+############################################################################
+
+import numpy as np
+
+
+class MarginalComputation:
+  @staticmethod
+  def _weight(evidces: dict[int, int], count: int) -> np.ndarray:
+    # The signature must be : Dict[int, int], int, **kwargs
+    return count

pyagrum/explain/_CustomShapleyCache.py

@@ -0,0 +1,110 @@
+############################################################################
+#   This file is part of the aGrUM/pyAgrum library.                        #
+#                                                                          #
+#   Copyright (c) 2005-2025 by                                             #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#                                                                          #
+#   The aGrUM/pyAgrum library is free software; you can redistribute it    #
+#   and/or modify it under the terms of either :                           #
+#                                                                          #
+#    - the GNU Lesser General Public License as published by               #
+#      the Free Software Foundation, either version 3 of the License,      #
+#      or (at your option) any later version,                              #
+#    - the MIT license (MIT),                                              #
+#    - or both in dual license, as here.                                   #
+#                                                                          #
+#   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    #
+#                                                                          #
+#   This aGrUM/pyAgrum library is distributed in the hope that it will be  #
+#   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          #
+#   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or 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.                                        #
+#                                                                          #
+#   See LICENCES for more details.                                         #
+#                                                                          #
+#   SPDX-FileCopyrightText: Copyright 2005-2025                            #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      #
+#                                                                          #
+#   Contact  : info_at_agrum_dot_org                                       #
+#   homepage : http://agrum.gitlab.io                                      #
+#   gitlab   : https://gitlab.com/agrumery/agrum                           #
+#                                                                          #
+############################################################################
+
+
+class CustomShapleyCache:
+  def __init__(self, max_capacity: int = 1000):
+    if max_capacity <= 0:
+      raise ValueError("max_capacity must be a positive integer.")
+    self._cache = {}  # Structure: {longueur_str: { (entier, str): valeur }}
+    self._current_k_index = -1  # Pour suivre l'indice k actuel
+    self._max_capacity = max_capacity  # Capacité maximale du cache en nombre d'éléments
+    self._current_size = 0  # Taille actuelle du cache
+
+  @staticmethod
+  def generate_keys(bn, target, feat, nodes):
+    key1 = tuple(nodes)  # Key1 represents the coalition.
+    key2 = tuple(
+      n for n in nodes if n != feat
+    )  # Key2 represents the coalition without the feature which is being evaluated.
+    if target is None:  # For SHALL Values
+      return key1, key2, None
+    # Key3 is the coalition without ONE ! node which is not in the minimal conditional set.
+    minimal = bn.minimalCondSet(
+      target, nodes
+    )  # Calculates the minimal conditional set for the target node given the nodes.
+    diff = next((n for n in nodes if n not in minimal), None)
+    if diff is not None:
+      key3 = tuple(n for n in nodes if n != diff)
+    else:
+      key3 = key1
+    return key1, key2, key3
+
+  def get(self, int_key: int, tuple_key: tuple):
+    tuple_len = len(tuple_key)
+    return self._cache[tuple_len].get((int_key, tuple_key), None)
+
+  def set(self, int_key: int, tuple_key: tuple, value):
+    tuple_len = len(tuple_key)
+    if tuple_len not in self._cache:
+      self._cache[tuple_len] = {}
+      self._current_k_index = tuple_len
+
+    # If it is the first time we add an entry of this length, we initialize the cache for this length.
+    if (int_key, tuple_key) not in self._cache[tuple_len]:
+      self._current_size += 1
+    self._cache[tuple_len][(int_key, tuple_key)] = value
+
+    # Check if we need to purge the cache
+    if self._current_size > self._max_capacity:
+      self._perform_purge()
+
+  def _perform_purge(self):
+    if self._current_k_index < 2:
+      return
+
+    str_len_to_purge = self._current_k_index - 2
+
+    # Purge all entries with length <= str_len_to_purge
+    for length in list(self._cache.keys()):
+      if length <= str_len_to_purge:
+        self._current_size -= len(self._cache[length])
+        del self._cache[length]
+
+  def __len__(self):
+    return self._current_size
+
+  def __str__(self):
+    # Affiche le cache par longueur de clé pour une meilleure visibilité
+    items_by_length = {k: len(v) for k, v in self._cache.items()}
+    return (
+      f"Cache (k={self._current_k_index}, size={self._current_size}/{self._max_capacity}): "
+      f"Contents by length: {items_by_length}"
+    )

pyagrum/explain/_Explainer.py

@@ -0,0 +1,176 @@
+############################################################################
+#   This file is part of the aGrUM/pyAgrum library.                        #
+#                                                                          #
+#   Copyright (c) 2005-2025 by                                             #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#                                                                          #
+#   The aGrUM/pyAgrum library is free software; you can redistribute it    #
+#   and/or modify it under the terms of either :                           #
+#                                                                          #
+#    - the GNU Lesser General Public License as published by               #
+#      the Free Software Foundation, either version 3 of the License,      #
+#      or (at your option) any later version,                              #
+#    - the MIT license (MIT),                                              #
+#    - or both in dual license, as here.                                   #
+#                                                                          #
+#   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    #
+#                                                                          #
+#   This aGrUM/pyAgrum library is distributed in the hope that it will be  #
+#   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          #
+#   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or 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.                                        #
+#                                                                          #
+#   See LICENCES for more details.                                         #
+#                                                                          #
+#   SPDX-FileCopyrightText: Copyright 2005-2025                            #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      #
+#                                                                          #
+#   Contact  : info_at_agrum_dot_org                                       #
+#   homepage : http://agrum.gitlab.io                                      #
+#   gitlab   : https://gitlab.com/agrumery/agrum                           #
+#                                                                          #
+############################################################################
+
+from abc import ABC, abstractmethod
+import pyagrum as gum
+from pyagrum.explain._FIFOCache import FIFOCache
+
+# Calculations
+import numpy as np
+import math
+from itertools import combinations
+from typing import Callable
+
+
+class Explainer(ABC):
+  """
+  ___Documentation___
+  """
+
+  def __init__(self, bn: gum.BayesNet):
+    """
+    Parameters:
+    ------
+    bn : pyagrum.BayesNet
+        The Bayesian Network.
+
+    Raises:
+    ------
+    TypeError : If bn is not a gum.BayesNet.
+    """
+    super().__init__()
+    if not isinstance(bn, gum.BayesNet):
+      raise TypeError("bn must be a gum.BayesNet instance, but got {}".format(type(bn)))
+    self.bn = bn
+    self.M = len(bn.nodes())  # Total number of nodes in the Bayesian Network.
+    self.feat_names = np.empty(self.M, dtype=object)  # Array to store feature names by their node ID.
+    for name in self.bn.names():
+      self.feat_names[self.bn.idFromName(name)] = name
+
+  @staticmethod
+  def _log(p: float):
+    # Applies the log function to the probability.
+    return np.log(p) if p > 0 else -np.inf
+
+  @staticmethod
+  def _logit(p: any):
+    # Applies the logit transformation to the probabilities.
+    p = np.asarray(p)  # Guarantee p is a numpy array.
+    with np.errstate(divide="ignore", invalid="ignore"):
+      result = np.log(p / (1 - p))
+    result = np.where(p == 0, 0.0, result)
+    result = np.where(p == 1, 0.0, result)
+    return result
+
+  @staticmethod
+  def _identity(x: any):
+    # Returns the input as is (identity function).
+    return x
+
+  def _labelToPos_row(self, x: np.ndarray, elements: list[int]) -> np.ndarray:
+    # Converts labels to positions for a single instance.
+    y = np.empty(shape=x.shape, dtype=int)
+    for i in elements:
+      try:
+        val = self.bn.variable(i).posLabel(x[i])
+      except:
+        val = int(x[i])
+      y[i] = val
+    return y
+
+  def _labelToPos_df(self, x: np.ndarray, elements: list[int]) -> np.ndarray:
+    # Converts labels to positions for multiple instances.
+    y = np.empty(shape=x.shape, dtype=int)  # Initialisation
+    posLabelVect = np.vectorize(lambda i, j: self.bn.variable(int(j)).posLabel(i))
+    for j in elements:
+      try:
+        self.bn.variable(j).posLabel(x[0, j])
+        y[:, j] = posLabelVect(x[:, j], j)
+      except NotImplementedError:
+        y[:, j] = x[:, j].astype(int)
+    return y
+
+  @staticmethod
+  def _extract(data: np.ndarray, tau: list[int], alpha: np.ndarray) -> np.ndarray:
+    # Extracts the data given the values in alpha for the nodes in tau.
+    mask = np.all(data[:, tau] == alpha, axis=1)
+    idx = np.nonzero(mask)[0]
+    return idx
+
+  @staticmethod
+  def _coalitions(elements_for_coalitions):
+    # Generates all possible coalitions from the given elements.
+    all_coalitions = []
+    for r in range(1, len(elements_for_coalitions) + 1):
+      for combo in combinations(elements_for_coalitions, r):
+        all_coalitions.append(list(combo))
+    return all_coalitions
+
+  @staticmethod
+  def _invcoeff_shap(m, s):
+    # Computes the inverse coefficient for the Shapley value formula.
+    return (m - s) * math.comb(m, s)
+
+  @staticmethod
+  def _shap_term(prob_with, prob_without, m, s):
+    return (prob_with - prob_without) / Explainer._invcoeff_shap(m, s)
+
+  def _value(
+    self, data: np.ndarray, counts: list[int], elements: list[int], sigma: list[int], cache: FIFOCache, **kwargs
+  ) -> float | np.ndarray:
+    # -- #
+    length: int = len(data)
+    func1: Callable = kwargs["func1"]
+    func2: Callable = kwargs["func2"]
+    params1: dict[str, any] = kwargs["params1"]
+    params2: dict[str, any] = kwargs["params2"]
+    # -- #
+
+    val = 0.0
+    norm = 0.0
+    for i in range(length):
+      evidces1 = {self.feat_names[key]: int(data[i, key]) for key in elements}
+      evidces2 = {self.feat_names[key]: int(data[i, key]) for key in sigma}
+      term1 = cache.get(tuple(data[i, elements]), None)
+      if term1 is None:
+        term1 = func1(evidces1, **params1)
+        cache[tuple(data[i, elements])] = term1
+
+      term2 = func2(evidces2, counts[i], **params2)
+      val += term1 * term2
+      norm += term2
+
+    return 0.0 if norm == 0.0 else val / norm
+
+  @abstractmethod
+  def compute(self, data: tuple | None, N=100):
+    # Computes the Shapley values for the target node based on the provided data.
+    # This method must be implemented in subclasses
+    raise NotImplementedError("This method must be implemented in subclasses.")

pyagrum/explain/_Explanation.py

@@ -0,0 +1,70 @@
+############################################################################
+#   This file is part of the aGrUM/pyAgrum library.                        #
+#                                                                          #
+#   Copyright (c) 2005-2025 by                                             #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#                                                                          #
+#   The aGrUM/pyAgrum library is free software; you can redistribute it    #
+#   and/or modify it under the terms of either :                           #
+#                                                                          #
+#    - the GNU Lesser General Public License as published by               #
+#      the Free Software Foundation, either version 3 of the License,      #
+#      or (at your option) any later version,                              #
+#    - the MIT license (MIT),                                              #
+#    - or both in dual license, as here.                                   #
+#                                                                          #
+#   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    #
+#                                                                          #
+#   This aGrUM/pyAgrum library is distributed in the hope that it will be  #
+#   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          #
+#   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or 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.                                        #
+#                                                                          #
+#   See LICENCES for more details.                                         #
+#                                                                          #
+#   SPDX-FileCopyrightText: Copyright 2005-2025                            #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      #
+#                                                                          #
+#   Contact  : info_at_agrum_dot_org                                       #
+#   homepage : http://agrum.gitlab.io                                      #
+#   gitlab   : https://gitlab.com/agrumery/agrum                           #
+#                                                                          #
+############################################################################
+
+from collections.abc import MutableMapping
+
+
+class Explanation(MutableMapping):
+  def __init__(self, values, importances, feature_names, data, baseline, func, values_type) -> None:
+    self._values = values
+    self.importances = importances
+    self.feature_names = feature_names
+    self.data = data
+    self.baseline = baseline
+    self.func = func
+    self.values_type = values_type
+
+  def __getitem__(self, key):
+    return self._values[key]
+
+  def __setitem__(self, key, value):
+    self._values[key] = value
+
+  def __delitem__(self, key):
+    del self._values[key]
+
+  def __iter__(self):
+    return iter(self._values)
+
+  def __len__(self):
+    return len(self._values)
+
+  def __repr__(self):
+    return f"Explanation(values={self._values})"

pyagrum/explain/_FIFOCache.py

@@ -0,0 +1,54 @@
+############################################################################
+#   This file is part of the aGrUM/pyAgrum library.                        #
+#                                                                          #
+#   Copyright (c) 2005-2025 by                                             #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#                                                                          #
+#   The aGrUM/pyAgrum library is free software; you can redistribute it    #
+#   and/or modify it under the terms of either :                           #
+#                                                                          #
+#    - the GNU Lesser General Public License as published by               #
+#      the Free Software Foundation, either version 3 of the License,      #
+#      or (at your option) any later version,                              #
+#    - the MIT license (MIT),                                              #
+#    - or both in dual license, as here.                                   #
+#                                                                          #
+#   (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html)    #
+#                                                                          #
+#   This aGrUM/pyAgrum library is distributed in the hope that it will be  #
+#   useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,          #
+#   INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or 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.                                        #
+#                                                                          #
+#   See LICENCES for more details.                                         #
+#                                                                          #
+#   SPDX-FileCopyrightText: Copyright 2005-2025                            #
+#       - Pierre-Henri WUILLEMIN(_at_LIP6)                                 #
+#       - Christophe GONZALES(_at_AMU)                                     #
+#   SPDX-License-Identifier: LGPL-3.0-or-later OR MIT                      #
+#                                                                          #
+#   Contact  : info_at_agrum_dot_org                                       #
+#   homepage : http://agrum.gitlab.io                                      #
+#   gitlab   : https://gitlab.com/agrumery/agrum                           #
+#                                                                          #
+############################################################################
+
+from collections import OrderedDict
+
+
+class FIFOCache(OrderedDict):
+  def __init__(self, maxlen, *args, **kwargs):
+    self.maxlen = maxlen
+    super().__init__(*args, **kwargs)
+
+  def __setitem__(self, key, value):
+    if key in self:
+      del self[key]  # pour mettre à jour l'ordre
+    elif len(self) >= self.maxlen:
+      self.popitem(last=False)  # retire le plus ancien
+    super().__setitem__(key, value)