=================== Metrics Description =================== This reference page provides an overview of the metrics available in the ``dyn-benchmark`` package for analyzing evolving communities and temporal networks. 1. Metrics Organization ----------------------- Metrics in the package are organized into several categories (handlers): .. list-table:: :widths: 35 65 :header-rows: 1 * - Category - Description * - ``graph_handler`` - Metrics for network structure at each snapshot * - ``graph_partition_handler`` - Metrics for community partition quality at each snapshot * - ``static_community_handler`` - Metrics for individual communities at specific snapshots * - ``static_community_graph_handler`` - Metrics for community structure within the network * - ``evolving_community_handler`` - Metrics for communities across their lifetime * - ``snapshot_handler`` - Metrics for temporal snapshots * - ``member_handler`` - Metrics for individual member behavior * - ``member_snapshot_handler`` - Metrics for members at specific snapshots * - ``flow_handler`` - Metrics for transitions between communities These handlers are useful for customizing the metrics you want to compute. For example, if you only want to compute community metrics, you can use the ``graph_partition_handler`` and ``static_community_handler`` handlers. Refer to the :doc:`Tutorial 3 Metrics Computation and Analysis <../tutorials/3_metrics_computation_analysis>` for more details on how to use these handlers. Heavy vs. Light Metrics ~~~~~~~~~~~~~~~~~~~~~~~ Some metrics are computationally intensive for large networks: - **Heavy metrics** (use with caution for large networks): - ``diameter`` - ``average_shortest_path_length`` - **Light metrics** (efficient for any network size): - ``number_of_nodes`` - ``number_of_edges`` - ``modularity`` - Most community and member metrics The package provides a predefined list of heavy metrics you can exclude from your analysis: .. code-block:: python from dyn.benchmark.metrics import graph_heavy_metrics # Create metrics computer excluding heavy metrics light_metrics = GroundtruthMetricsComputer( graph=[m for m in graph_handler.funcs if m not in graph_heavy_metrics] ) 2. Static Network and Community Metrics --------------------------------------- This section focuses on metrics that evaluate the structure of networks and communities at each snapshot. Graph Structure Metrics ~~~~~~~~~~~~~~~~~~~~~~~ Graph metrics analyze the structural properties of the network at each snapshot and can be accessed through ``metrics["graph"]``. These metrics help understand the overall connectivity patterns and topological features of the network. .. list-table:: Graph Structure Metrics :widths: 30 70 :header-rows: 1 * - Metric - Description * - ``number_of_nodes`` - Count of nodes in the network. * - ``number_of_edges`` - Count of edges in the network. * - ``diameter`` - Maximum shortest path length in the graph. Returns `nan` if the graph has no edges or is not connected. * - ``average_shortest_path_length`` - Average of all shortest paths. * - ``ccf`` - Average clustering coefficient. * - ``nb_connected_components`` - Number of connected components. Community Partition Quality ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Partition metrics evaluate the quality of community division at each snapshot and can be accessed through ``metrics["graph_partition"]``. These metrics quantify how well-defined the community structure is within the network. .. list-table:: Community Partition Metrics :widths: 30 70 :header-rows: 1 * - Metric - Description * - ``modularity`` - Measure of the quality of community division. * - ``coverage`` - Fraction of intra-community edges. * - ``performance`` - Ratio of intra-community edges plus inter-community non-edges to the total number of potential edges. Measures both the presence of edges within communities and the absence of edges between communities. * - ``p_in`` - Probability of edge between nodes in same community. * - ``p_out`` - Probability of edge between nodes in different communities. Static Community Metrics ~~~~~~~~~~~~~~~~~~~~~~~~ Static community metrics analyze individual communities at specific snapshots and can be accessed through ``metrics["static_community"]``. These metrics help understand the characteristics and dynamics of each community at a particular point in time. .. list-table:: Static Community Metrics :widths: 30 70 :header-rows: 1 * - Metric - Description * - ``size`` - Number of members in the community. * - ``turnover_ratio`` - Ratio calculated as the sum of incoming members (immigrants) and outgoing members (emigrants) divided by twice the size of the predecessor community. Measures how much the community's membership changed compared to its previous snapshot. * - ``emigrants_ratio`` - Fraction of members that left the community. * - ``change_size_ratio`` - Relative change in size from previous snapshot. Community Embedding in Network ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Static community graph metrics analyze how communities are embedded within the network and can be accessed through ``metrics["static_community_graph"]``. These metrics help understand the relationship between communities and the overall network structure. .. list-table:: Community Embedding Metrics :widths: 30 70 :header-rows: 1 * - Metric - Description * - ``cut_ratio`` - Fraction of existing external edges out of all possible. * - ``conductance`` - Fraction of total edge volume that points outside the community0 * - ``scaled_density`` - Ratio of internal edges to maximum possible internal edges. 3. Evolving Community and Temporal Metrics ------------------------------------------ This section focuses on metrics that evaluate the evolution of communities over time. Evolving Community Metrics ~~~~~~~~~~~~~~~~~~~~~~~~~~ Evolving community metrics track communities across their entire lifespan and can be accessed through ``metrics["evolving_community"]``. These metrics provide insights into the long-term behavior and stability of communities. .. list-table:: Evolving Community Metrics :widths: 30 70 :header-rows: 1 * - Metric - Description * - ``lifetime`` - Number of snapshots a community exists. * - ``begin_snapshot`` - First snapshot where the community appears. * - ``begin_size`` - Initial size of the community. Snapshot Evolution Metrics ~~~~~~~~~~~~~~~~~~~~~~~~~~ Snapshot metrics analyze the properties of each temporal snapshot and can be accessed through ``metrics["snapshot"]``. These metrics provide insights into how the community structure evolves from one snapshot to the next. .. list-table:: Snapshot Metrics :widths: 30 70 :header-rows: 1 * - Metric - Description * - ``communities_count`` - Number of communities at this snapshot. * - ``turnover_ratio`` - Ratio calculated as the sum of incoming and outgoing members divided by twice the size of the previous community. Measures the rate of change in community composition between two snapshots. Member Behavior Analysis ~~~~~~~~~~~~~~~~~~~~~~~~ Member metrics analyze the behavior of individual members across snapshots and can be accessed through ``metrics["member"]``. These metrics help understand how nodes participate in communities over time. .. list-table:: Member Behavior Metrics :widths: 30 70 :header-rows: 1 * - Metric - Description * - ``snapshots_online`` - Number of snapshots the member is active. * - ``communities_visited`` - Number of different communities the member belongs to. Community Transition Analysis ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Flow metrics analyze the transitions between communities and can be accessed through ``metrics["flow"]``. These metrics help understand how members move between communities over time. .. list-table:: Community Transition Metrics :widths: 30 70 :header-rows: 1 * - Metric - Description * - ``relative_emigrants_flow`` - Ratio of members flowing from one community to another, excluding flows to the direct successor community. Measures only the relative migration between different evolving communities. .. _community-comparison-metrics: 4. Community Comparison Metrics ------------------------------- Metrics for comparing different community structures: .. list-table:: :widths: 25 75 :header-rows: 1 * - Metric - Description * - ``adjusted_rand`` - Adjusted Rand Index (chance-corrected similarity) * - ``normalized_mutual_information`` - Normalized measure of similarity between partitions * - ``variation_info`` - Variation of Information (distance metric) * - ``jaccard`` - Jaccard similarity between partitions These metrics are available through the ``assess_partition_metrics`` and ``assess_transition_metrics`` functions: .. code-block:: python from dyn.benchmark.assess import assess_partition_metrics # Compare partitions partition_metrics = assess_partition_metrics(groundtruth.tcommlist, detected_tcommlist) # Compare transitions transition_metrics = assess_transition_metrics( groundtruth.tcommlist, detected_tcommlist, dt_min=1, dt_max=3 )