smx.graph.centrality
====================

.. py:module:: smx.graph.centrality

.. autoapi-nested-parse::

   LRC (Local Reaching Centrality) computation and cross-seed aggregation.



Functions
---------

.. autoapisummary::

   smx.graph.centrality.compute_lrc
   smx.graph.centrality.aggregate_lrc_across_seeds


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

.. py:function:: compute_lrc(graph: networkx.DiGraph, predicates_df: pandas.DataFrame) -> pandas.DataFrame

   Compute Local Reaching Centrality (LRC) for every node of *graph*.

   LRC measures how well a node can reach other nodes in the graph,
   weighted by edge weights.  Higher LRC → more central / important.

   Parameters
   ----------
   graph : nx.DiGraph
       Directed predicate graph (e.g., from
       :class:`smx.graph.builder.PredicateGraphBuilder`).
   predicates_df : pd.DataFrame
       Predicate catalogue with columns ``'rule'``, ``'zone'``,
       ``'thresholds'``, ``'operator'``.

   Returns
   -------
   pd.DataFrame
       Columns: ``Node``, ``Local_Reaching_Centrality``, ``Zone``,
       ``Threshold``, ``Operator``.  Sorted descending by LRC.


.. py:function:: aggregate_lrc_across_seeds(lrc_by_seed: Dict[int, pandas.DataFrame], random_seeds: List[int]) -> Tuple[pandas.DataFrame, pandas.DataFrame]

   Aggregate per-seed LRC DataFrames into a mean-aggregated ranking.

   Parameters
   ----------
   lrc_by_seed : dict
       ``{seed: lrc_df}`` where each *lrc_df* is returned by
       :func:`compute_lrc` (must have column ``'Node'`` plus
       ``'Local_Reaching_Centrality'``, ``'Zone'``, ``'Threshold'``,
       ``'Operator'``).
   random_seeds : list of int
       Seeds to include in the aggregation (keys of *lrc_by_seed*).

   Returns
   -------
   lrc_summed_df : pd.DataFrame
       Mean-aggregated LRC for all predicates, sorted descending.
   lrc_summed_unique_df : pd.DataFrame
       Zone-deduplicated version of *lrc_summed_df* (one row per zone),
       keeping the highest-ranked predicate per zone.