pyAgrum-nightly 2.1.1.9.dev202506061747485979__cp310-abi3-manylinux2014_aarch64.whl → 2.3.1.9.dev202601031765915415__cp310-abi3-manylinux2014_aarch64.whl

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)

pyagrum/explain/_ShallCausalValues.py

@@ -0,0 +1,204 @@
+############################################################################
+#   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
+from pyagrum.explain._ShallValues import ShallValues
+from pyagrum.explain._CustomShapleyCache import CustomShapleyCache
+from pyagrum.explain._ComputationCausal import CausalComputation
+from pyagrum.explain._FIFOCache import FIFOCache
+
+import numpy as np
+
+
+class CausalShallValues(ShallValues, CausalComputation):
+  """
+  The CausalShallValues class computes the Causal Shall values in a Bayesian Network.
+  """
+
+  def __init__(self, bn: gum.BayesNet, background: tuple | None, sample_size: int = 1000, log: bool = True):
+    """
+    Note 1 : All rows in the background data that contain NaN values in columns corresponding to variables in the Bayesian Network will be dropped.
+    Note 2 : In comparison to Marginal and Conditional Shall values it is impossible to calculate empirical probabilities 'true to the data'.
+    We are forced to calculate probabilités 'true to the model'.
+
+
+    Parameters:
+    ------
+     bn : pyagrum.BayesNet
+        The Bayesian Network.
+    background : tuple[pandas.DataFrame, bool] | None
+        A tuple containing a pandas DataFrame and a boolean indicating whether the DataFrame includes labels or positional values.
+    sample_size : int
+        The size of the background sample to generate if `background` is None.
+    log : bool
+        If True, applies a logarithmic transformation to the probabilities.
+
+    Raises
+    ------
+    TypeError : If bn is not a gum.BayesNet instance, background is not a tuple.
+    ValueError : If background data does not contain all variables present in the Bayesian Network or if
+        background data is empty after rows with NaNs were dropped.
+
+    Raises:
+    ------
+    TypeError : If bn is not a gum.BayesNet instance, background is not a tuple.
+    ValueError : If background data does not contain all variables present in the Bayesian Network or if
+        background data is empty after rows with NaNs were dropped.
+    """
+
+    super().__init__(bn, background, sample_size, log)
+    self.baseline = self._value(
+      data=self._data,
+      counts=self.counts,
+      elements=self.vars_ids,
+      sigma=self.vars_ids,
+      cache=FIFOCache(100),
+      func1=self._joint,
+      params1={},
+      func2=self._weight,
+      params2={"doLazy": gum.LazyPropagation(self.bn)},
+    )
+
+  def _coalition_contribution(self, posterior_prob_with, posterior_prob_without, m, s):
+    return (posterior_prob_with - posterior_prob_without) / self._invcoeff_shap(m, s)
+
+  def _shall_1dim(self, x):
+    contributions = np.zeros(self.M)  # M : number of nodes in BN
+
+    # Caches
+    custom_cache = CustomShapleyCache(5000)
+    fifo_cache = FIFOCache(1000)
+    # Sets the baseline probability in the cache.
+    custom_cache.set(0, (), self.baseline)
+    # Compute the coalitions
+    coalitions = self._coalitions(self.vars_ids)
+
+    for tau in coalitions:
+      # self.ie.eraseAllEvidence()
+      doNet = self._doCalculus(self.bn, tau)  # new BN
+      sigma = self._outOfCoalition(tau, self.vars_ids)  # all nodes \ tau
+
+      doInst = gum.Instantiation()
+      for var in doNet.ids(self.feat_names):
+        doInst.add(doNet.variable(var))
+
+      # Instanciation of tau
+      alpha = x[tau]  # extract columns in tau
+      if sigma != []:
+        self._chgCpt(doNet, tau, alpha)
+        doLazy = gum.LazyPropagation(doNet)
+        doLazy.addTarget(tau[0])  # see if target should be added for optimization
+        idx = self._extract(self._data, tau, alpha)
+        # Compute the value for this coalition.
+        joint_with = self._value(
+          data=self._data[idx],
+          counts=self.counts[idx],
+          elements=self.vars_ids,
+          sigma=sigma,
+          cache=fifo_cache,
+          func1=self._joint,
+          params1={},
+          func2=self._weight,
+          params2={"doLazy": doLazy},
+        )
+      else:
+        self.inst.fromdict({self.feat_names[key]: int(val) for key, val in zip(tau, alpha)})
+        joint = self.bn.jointProbability(self.inst)
+        joint_with = self.func(joint)
+
+      custom_cache.set(0, tuple(tau), joint_with)
+      # Contribution of each feature
+      for t in tau:
+        key = tuple((f for f in tau if f != t))
+        joint_without = custom_cache.get(0, key)
+        contributions[t] += self._coalition_contribution(joint_with, joint_without, len(self.vars_ids), len(tau) - 1)
+    return contributions
+
+  def _shall_ndim(self, x):
+    # Initialisation
+    contributions = np.zeros((self.M, len(x)))
+
+    # Caches
+    custom_cache = CustomShapleyCache(5000)
+    fifo_cache = FIFOCache(1000)
+    # Sets the baseline probability in the cache.
+    custom_cache.set(0, (), self.baseline)
+    # Compute the coalitions
+    coalitions = self._coalitions(self.vars_ids)
+
+    for tau in coalitions:
+      doNet = self._doCalculus(self.bn, tau)
+      sigma = self._outOfCoalition(tau, self.vars_ids)
+
+      for i in range(len(x)):
+        alpha = x[i, tau]
+        if sigma != []:
+          # Instanciation of tau
+          self._chgCpt(doNet, tau, alpha)  # BN knowing alpha
+          doLazy = gum.LazyPropagation(doNet)
+          doLazy.addTarget(tau[0])  # just to speed up the calculation
+          idx = self._extract(self._data, tau, alpha)
+          # Compute the value for this coalition.
+          joint_with = self._value(
+            data=self._data[idx],
+            counts=self.counts[idx],
+            elements=self.vars_ids,
+            sigma=sigma,
+            cache=fifo_cache,
+            func1=self._joint,
+            params1={},
+            func2=self._weight,
+            params2={"doLazy": doLazy},
+          )
+
+        else:
+          self.inst.fromdict({self.feat_names[key]: int(val) for key, val in zip(tau, alpha)})
+          joint = self.bn.jointProbability(self.inst)
+          joint_with = self.func(joint)
+
+        custom_cache.set(i, tuple(tau), joint_with)
+        # Contribution of each feature
+        for t in tau:
+          key = tuple((f for f in tau if f != t))
+          joint_without = custom_cache.get(i, key) if len(key) > 0 else custom_cache.get(0, ())
+          contributions[t, i] += self._coalition_contribution(
+            joint_with, joint_without, len(self.vars_ids), len(tau) - 1
+          )
+    return contributions

pyagrum/explain/_ShallConditionalValues.py

@@ -0,0 +1,155 @@
+############################################################################
+#   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
+
+from pyagrum.explain._ShallValues import ShallValues
+from pyagrum.explain._CustomShapleyCache import CustomShapleyCache
+from pyagrum.explain._FIFOCache import FIFOCache
+from pyagrum.explain._ComputationConditional import ConditionalComputation
+
+import numpy as np
+from warnings import warn
+
+
+class ConditionalShallValues(ShallValues, ConditionalComputation):
+  """
+  The ConditionalShallValues class computes the conditional Shall values in a Bayesian Network.
+  """
+
+  def __init__(self, bn: gum.BayesNet, background: tuple | None, sample_size: int = 1000, log: bool = True):
+    """
+    Note 1 : All rows in the background data that contain NaN values in columns corresponding to variables in the Bayesian Network will be dropped.
+    Note 2 : For small databases SHALL values can be incorrect.
+
+    Parameters:
+    ------
+     bn : pyagrum.BayesNet
+        The Bayesian Network.
+    background : tuple[pandas.DataFrame, bool] | None
+        A tuple containing a pandas DataFrame and a boolean indicating whether the DataFrame includes labels or positional values.
+    sample_size : int
+        The size of the background sample to generate if `background` is None.
+    log : bool
+        If True, applies a logarithmic transformation to the probabilities.
+
+    Raises
+    ------
+    TypeError : If bn is not a gum.BayesNet instance, background is not a tuple.
+    ValueError : If background data does not contain all variables present in the Bayesian Network or if
+        background data is empty after rows with NaNs were dropped.
+
+    Raises:
+    ------
+    TypeError : If bn is not a gum.BayesNet instance, background is not a tuple.
+    ValueError : If background data does not contain all variables present in the Bayesian Network or if
+        background data is empty after rows with NaNs were dropped.
+    """
+
+    super().__init__(bn, background, sample_size, log)  # Initializes the ShapleyValues class.
+    self.baseline = self._value(
+      data=self._data,
+      counts=self.counts,
+      elements=self.vars_ids,
+      sigma=[],
+      cache=FIFOCache(100),
+      func1=self._joint,
+      params1={},
+      func2=self._weight,
+      params2={},
+    )
+
+  def _coalition_contribution(self, k, ex, feature, nodes_id, nodes_vals, cache, fifo_cache):
+    # key2 is always set since subsets are sorted by length
+    key1, key2, _ = cache.generate_keys(self.bn, None, feature, nodes_id)
+    # key1 : nodes_id, key2 : nodes id without feature
+    if k == 0:
+      idx = self._extract(self._data, nodes_id, nodes_vals)
+      # warn(f"Extracted database is empty ({self.feat_names[nodes_id]} = {nodes_vals}). Conditional SHALL values may be incorrect. ")
+      cache.set(
+        ex,
+        key1,
+        self._value(
+          data=self._data[idx],
+          counts=self.counts[idx],
+          elements=self.vars_ids,
+          sigma=[],
+          cache=fifo_cache,
+          func1=self._joint,
+          params1={},
+          func2=self._weight,
+          params2={},
+        ),
+      )
+
+    joint_prob_with = cache.get(ex, key1)  # with feature
+    joint_prob_without = cache.get(ex, key2) if len(key1) > 1 else cache.get(-1, "")  # without feature
+    return (joint_prob_with - joint_prob_without) / self._invcoeff_shap(len(self.vars_ids), len(nodes_id) - 1)
+
+  def _shall_1dim(self, x) -> np.ndarray:
+    contributions = np.zeros((self.M))  # Initializes contributions array.
+    fifo_cache = FIFOCache(2000)
+    cache = CustomShapleyCache(5000)  # Initializes the custom cache.
+    cache.set(-1, "", self.baseline)  # Sets the baseline probability in the cache.
+    coalitions = self._coalitions(self.vars_ids)  # Generates coalitions.
+    for nodes_id in coalitions:
+      nodes_vals = x[nodes_id]  # Gets the values of the nodes in the coalition.
+      for k, feature in enumerate(nodes_id):
+        # Accumulates the contribution for each feature.
+        contributions[feature] += self._coalition_contribution(
+          k, 0, int(feature), nodes_id, nodes_vals, cache, fifo_cache
+        )
+    return contributions
+
+  def _shall_ndim(self, x) -> np.ndarray:
+    contributions = np.zeros((self.M, len(x)))  # Initializes contributions array.
+    fifo_cache = FIFOCache(2000)
+    cache = CustomShapleyCache(5000)  # Initializes the custom cache.
+    cache.set(-1, "", self.baseline)  # Sets the baseline probability in the cache.
+
+    coalitions = self._coalitions(self.vars_ids)  # Generates coalitions.
+    for i, nodes_id in enumerate(coalitions):
+      data_vals = x[:, nodes_id]  # Gets the values of the nodes in the coalition.
+      for ex, nodes_vals in enumerate(data_vals):
+        for k, feature in enumerate(nodes_id):
+          contributions[feature, ex] += self._coalition_contribution(
+            k, ex, int(feature), nodes_id, nodes_vals, cache, fifo_cache
+          )
+    return contributions