smx.graph.builder
=================

.. py:module:: smx.graph.builder

.. autoapi-nested-parse::

   PredicateGraphBuilder: construct a directed predicate graph.

   Edges are added between consecutive predicates ordered by a ranking metric
   inside each bag, and weights are accumulated across bags.  Bidirectional
   edges are resolved by keeping only the higher-weight direction.



Classes
-------

.. autoapisummary::

   smx.graph.builder.PredicateGraphBuilder


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

.. py:class:: PredicateGraphBuilder(random_state: int = 42, show_details: bool = True, var_exp: bool = False, pca_info_dict: Optional[Dict] = None)

   Build a directed predicate graph from bags and metric rankings.

   Edge weights derive from the ranking metric of the *source* predicate in
   each bag.  When the same directed edge appears in multiple bags, the
   weights are accumulated (summed).  Bidirectional edges (A→B and B→A)
   are resolved by:

   * keeping the edge with the higher accumulated weight;
   * breaking ties randomly.

   Parameters
   ----------
   random_state : int, default 42
       Seed for random tie-breaking of bidirectional edges.
   show_details : bool, default True
       Print details about identified and removed bidirectional edges.
   var_exp : bool, default False
       When ``True``, multiply edge weights by the PC1 explained variance of
       the source predicate's spectral zone.  Requires *pca_info_dict*.
   pca_info_dict : dict, optional
       ``{zone_name: {'variance_explained': float, ...}}`` as returned by
       :class:`smx.zones.aggregation.ZoneAggregator` (``pca_info_`` attribute).
       Required when ``var_exp=True``.


   .. py:attribute:: random_state
      :value: 42



   .. py:attribute:: show_details
      :value: True



   .. py:attribute:: var_exp
      :value: False



   .. py:attribute:: pca_info_dict
      :value: None



   .. py:method:: build(bags_result: Dict[str, Dict[str, pandas.DataFrame]], predicate_ranking_dict: Dict[str, pandas.DataFrame], metric_column: str = 'Covariance') -> networkx.DiGraph

      Build and return the directed predicate graph.

      Parameters
      ----------
      bags_result : dict
          Bags as returned by :class:`smx.predicates.bagging.PredicateBagger`.
      predicate_ranking_dict : dict
          ``{bag_name: DataFrame(['Predicate', metric_column])}``
          as returned by a :class:`smx.predicates.metrics.BasePredicateMetric`
          subclass.
      metric_column : str, default ``'Covariance'``
          Name of the metric column in *predicate_ranking_dict*.

      Returns
      -------
      nx.DiGraph
          Directed graph with ``'weight'`` edge attributes.