mbdlyb.formalisms.bayesnet.base
===============================

.. py:module:: mbdlyb.formalisms.bayesnet.base

.. autoapi-nested-parse::

   Bayesian Network base classes for node and network representation.

   This module provides the core classes for building and managing Bayesian networks
   using the pyAgrum library as the backend. It includes node classes with conditional
   probability table (CPT) support and automatic parent splitting for handling complex
   relationships.

   Classes:
       BNDependency: Represents a dependency relationship between Bayesian network nodes.
       BNElement: Abstract base class for elements in a Bayesian network.
       BayesNode: A probabilistic variable node in a Bayesian network.
       BayesAutoSplitNode: A specialized node with automatic parent splitting.
       BayesNet: The main Bayesian network container and manager.



Attributes
----------

.. autoapisummary::

   mbdlyb.formalisms.bayesnet.base.MAX_PARENTS


Classes
-------

.. autoapisummary::

   mbdlyb.formalisms.bayesnet.base.BNDependency
   mbdlyb.formalisms.bayesnet.base.BNElement
   mbdlyb.formalisms.bayesnet.base.BayesAutoSplitNode
   mbdlyb.formalisms.bayesnet.base.BayesNet
   mbdlyb.formalisms.bayesnet.base.BayesNode


Module Contents
---------------

.. py:class:: BNDependency(source: MBDNode, target: MBDNode, net: Optional[MBDNet] = None)

   Bases: :py:obj:`mbdlyb.MBDDependency`


   Represents a dependency relationship in a Bayesian network.

   This class encapsulates a dependency between two nodes in a Bayesian network,
   where one node (parent) influences the conditional probability of another node
   (child).


.. py:class:: BNElement(name: str, net: Optional[MBDNet] = None)

   Bases: :py:obj:`mbdlyb.MBDElement`


   Abstract base class for Bayesian network elements.

   Defines the interface for creating Bayesian network nodes and connections
   within a pyAgrum BayesNet structure.


   .. py:method:: create_bn_connections(bn: pyagrum.BayesNet)
      :abstractmethod:


      Create connections (arcs) in the Bayesian network.

      Establishes the edges from parent nodes to this node and fills the
      conditional probability tables.

      :param bn: The pyAgrum BayesNet to add connections to.

      :raises NotImplementedError: This method must be implemented by subclasses.



   .. py:method:: create_bn_node(bn: pyagrum.BayesNet, node_sets: dict[Type[mbdlyb.MBDNode], list[int]])
      :abstractmethod:


      Create a node in the Bayesian network.

      :param bn: The pyAgrum BayesNet to add the node to.
      :param node_sets: A dictionary mapping node types to lists of node IDs.

      :raises NotImplementedError: This method must be implemented by subclasses.



.. py:class:: BayesAutoSplitNode(name: str, net: Optional[MBDNet] = None)

   Bases: :py:obj:`BayesNode`


   A Bayesian network node with automatic parent splitting capability.

   When a node has too many parents (exceeding MAX_PARENTS), this class
   automatically splits the parents into groups and creates intermediate nodes
   to handle the large parent set while maintaining probability correctness.

   :ivar _split_preserve_classes: List of node classes whose parents should not be split.
   :ivar _parent_split: Mapping of split node FQNs to their parent lists, or None if no split.



   .. py:method:: create_bn_connections(bn: pyagrum.BayesNet)

      Create connections with automatic parent splitting.

      If parents were split, creates connections to intermediate split nodes.
      Otherwise, delegates to parent class for standard connection creation.

      :param bn: The pyAgrum BayesNet to add connections to.



   .. py:method:: create_bn_node(bn: pyagrum.BayesNet, node_sets: dict[Type[mbdlyb.MBDNode], list[int]])

      Create this node in the Bayesian network with automatic parent splitting.

      If the number of parents exceeds MAX_PARENTS, creates intermediate split nodes
      to handle the large parent set. Otherwise, delegates to parent class.

      :param bn: The pyAgrum BayesNet to add this node to.
      :param node_sets: A dictionary mapping node types to lists of node IDs.



.. py:class:: BayesNet(name: str, net: Optional[MBDNet] = None)

   Bases: :py:obj:`BNElement`, :py:obj:`mbdlyb.MBDNet`


   A Bayesian network container and reasoning structure.

   Manages a collection of Bayesian network nodes and their relationships,
   providing methods to convert the abstract representation into a pyAgrum
   BayesNet for inference and analysis.

   :ivar elements: Dictionary mapping element names to BNElement instances.



   .. py:method:: create_bn_connections(bn: pyagrum.BayesNet)

      Add all connections to the Bayesian network.

      Iterates through all BNElement instances and creates their connections
      (arcs and CPTs) in the pyAgrum BayesNet structure.

      :param bn: The pyAgrum BayesNet to add connections to.



   .. py:method:: create_bn_node(bn: pyagrum.BayesNet, node_sets: dict[Type[mbdlyb.MBDNode], list[int]])

      Add all nodes to the Bayesian network.

      Iterates through all BNElement instances and creates them in the pyAgrum
      BayesNet structure.

      :param bn: The pyAgrum BayesNet to add nodes to.
      :param node_sets: A dictionary mapping node types to lists of node IDs.



   .. py:method:: get_bn_nodes() -> list[BNElement]

      Get all Bayesian network elements.

      :returns: A list of all BNElement instances in this network.



   .. py:method:: to_bn() -> tuple[pyagrum.BayesNet, dict[Type[mbdlyb.MBDNode], list[int]]]

      Convert this abstract network to a pyAgrum BayesNet.

      Creates a complete Bayesian network with all nodes and connections,
      including conditional probability tables.

      :returns:         - The pyAgrum BayesNet instance.
                        - A dictionary mapping node types to lists of their pyAgrum IDs.
      :rtype: A tuple containing



.. py:class:: BayesNode[T](name: str, net: Optional[MBDNet] = None)

   Bases: :py:obj:`BNElement`, :py:obj:`mbdlyb.formalisms.CPTEnabledNode`\ [\ :py:obj:`T`\ ]


   A probabilistic node in a Bayesian network.

   Represents a random variable with discrete states and conditional probability
   tables (CPTs) that define the node's probability distribution given its parents.

   :ivar _PARENT_RELATION_TYPE: The type of dependency used in this network.


   Type Parameters:
           T: The type of states this node can take.


   .. py:method:: create_bn_connections(bn: pyagrum.BayesNet)

      Create connections from parent nodes to this node.

      Establishes arcs from all parent nodes to this node and fills the
      conditional probability table with values computed from the CPT.

      :param bn: The pyAgrum BayesNet to add connections to.



   .. py:method:: create_bn_node(bn: pyagrum.BayesNet, node_sets: dict[Type[mbdlyb.MBDNode], list[int]])

      Create this node in the Bayesian network.

      Adds the node as a variable to the BayesNet and registers it in the
      node_sets dictionary for later processing.

      :param bn: The pyAgrum BayesNet to add this node to.
      :param node_sets: A dictionary mapping node types to lists of node IDs.

      :raises AssertionError: If bn is None.



   .. py:method:: create_variable(bn: pyagrum.BayesNet, name: str, label: str, states: list[T]) -> int
      :staticmethod:


      Create a new variable in the Bayesian network.

      :param bn: The pyAgrum BayesNet to add the variable to.
      :param name: The unique name of the variable.
      :param label: The human-readable label for the variable.
      :param states: A list of possible state values for this variable.

      :returns: The node ID assigned by pyAgrum for the newly created variable.



.. py:data:: MAX_PARENTS
   :value: 10