py3plex 2.0.1__tar.gz → 2.0.6__tar.gz

{py3plex-2.0.1/py3plex.egg-info → py3plex-2.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py3plex
-Version: 2.0.1
+Version: 2.0.6
 Summary: A Multilayer network analysis python3 library
 Author-email: Blaž Škrlj <blaz.skrlj@ijs.si>
 License: MIT
@@ -106,19 +106,22 @@ Dynamic: license-file
 <img src="https://github.com/user-attachments/assets/47e16a25-cd58-41eb-9ccd-b40191758d91" alt="py3plex logo" width="400">
 
 [![Tests](https://github.com/SkBlaz/py3plex/actions/workflows/tests.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/tests.yml)
+[![Test coverage](https://img.shields.io/badge/test_coverage-40.1%25-green)](https://github.com/SkBlaz/py3plex/actions/workflows/tests.yml)
+[![Type Coverage](https://img.shields.io/badge/type_coverage-79.1%25-yellowgreen)](https://github.com/SkBlaz/py3plex/actions/workflows/type-coverage.yml)
 [![Examples](https://github.com/SkBlaz/py3plex/actions/workflows/examples.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/examples.yml)
 [![Tutorial](https://github.com/SkBlaz/py3plex/actions/workflows/tutorial-validation.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/tutorial-validation.yml)
 [![Code Quality](https://github.com/SkBlaz/py3plex/actions/workflows/code-quality.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/code-quality.yml)
 [![Benchmarks](https://github.com/SkBlaz/py3plex/actions/workflows/benchmarks.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/benchmarks.yml)
 [![Documentation](https://github.com/SkBlaz/py3plex/actions/workflows/doc-coverage.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/doc-coverage.yml)
 [![Formal Verification](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml)
+[![Lean formal verification](https://github.com/SkBlaz/py3plex/actions/workflows/formal.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/formal.yml)
 [![Fuzzing](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml)
-[![PyPI version](https://img.shields.io/pypi/v/py3plex.svg)](https://pypi.org/project/py3plex/)
+[![PyPI version](https://img.shields.io/pypi/v/py3plex.svg?cacheSeconds=300)](https://pypi.org/project/py3plex/)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/py3plex)](https://pypistats.org/packages/py3plex)
 ![CLI Tool](https://img.shields.io/badge/CLI%20Tool-Available-brightgreen)
 ![Docker](https://img.shields.io/badge/Docker-Available-blue)
-![Lines of Code](https://img.shields.io/badge/lines-211.9K-blue)
-![Test Count](https://img.shields.io/badge/tests-9.3K-blue)
+![Lines of Code](https://img.shields.io/badge/lines-213.6K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.7K-blue)
 
 *Multilayer networks* are complex networks with additional information assigned to nodes or edges (or both). This library includes
 some of the state-of-the-art algorithms for decomposition, visualization and analysis of such networks.

{py3plex-2.0.1 → py3plex-2.0.6}/README.md

@@ -2,19 +2,22 @@
 <img src="https://github.com/user-attachments/assets/47e16a25-cd58-41eb-9ccd-b40191758d91" alt="py3plex logo" width="400">
 
 [![Tests](https://github.com/SkBlaz/py3plex/actions/workflows/tests.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/tests.yml)
+[![Test coverage](https://img.shields.io/badge/test_coverage-40.1%25-green)](https://github.com/SkBlaz/py3plex/actions/workflows/tests.yml)
+[![Type Coverage](https://img.shields.io/badge/type_coverage-79.1%25-yellowgreen)](https://github.com/SkBlaz/py3plex/actions/workflows/type-coverage.yml)
 [![Examples](https://github.com/SkBlaz/py3plex/actions/workflows/examples.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/examples.yml)
 [![Tutorial](https://github.com/SkBlaz/py3plex/actions/workflows/tutorial-validation.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/tutorial-validation.yml)
 [![Code Quality](https://github.com/SkBlaz/py3plex/actions/workflows/code-quality.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/code-quality.yml)
 [![Benchmarks](https://github.com/SkBlaz/py3plex/actions/workflows/benchmarks.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/benchmarks.yml)
 [![Documentation](https://github.com/SkBlaz/py3plex/actions/workflows/doc-coverage.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/doc-coverage.yml)
 [![Formal Verification](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/verify.yml)
+[![Lean formal verification](https://github.com/SkBlaz/py3plex/actions/workflows/formal.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/formal.yml)
 [![Fuzzing](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml/badge.svg)](https://github.com/SkBlaz/py3plex/actions/workflows/fuzzing.yml)
-[![PyPI version](https://img.shields.io/pypi/v/py3plex.svg)](https://pypi.org/project/py3plex/)
+[![PyPI version](https://img.shields.io/pypi/v/py3plex.svg?cacheSeconds=300)](https://pypi.org/project/py3plex/)
 [![PyPI - Downloads](https://img.shields.io/pypi/dm/py3plex)](https://pypistats.org/packages/py3plex)
 ![CLI Tool](https://img.shields.io/badge/CLI%20Tool-Available-brightgreen)
 ![Docker](https://img.shields.io/badge/Docker-Available-blue)
-![Lines of Code](https://img.shields.io/badge/lines-211.9K-blue)
-![Test Count](https://img.shields.io/badge/tests-9.3K-blue)
+![Lines of Code](https://img.shields.io/badge/lines-213.6K-blue)
+![Test Count](https://img.shields.io/badge/tests-9.7K-blue)
 
 *Multilayer networks* are complex networks with additional information assigned to nodes or edges (or both). This library includes
 some of the state-of-the-art algorithms for decomposition, visualization and analysis of such networks.

{py3plex-2.0.1 → py3plex-2.0.6}/py3plex/__init__.py

@@ -51,8 +51,8 @@ For detailed documentation, see: https://skblaz.github.io/py3plex/
 """
 
 # Version information
-__version__ = "2.0.1"
-__api_version__ = "2.0.1"
+__version__ = "2.0.6"
+__api_version__ = "2.0.6"
 
 from py3plex.core.multinet import multi_layer_network
 from py3plex.core.types import (

py3plex-2.0.6/py3plex/_safe_expression.py

@@ -0,0 +1,101 @@
+"""Evaluate the small expression language used by filters and dynamics rules."""
+
+import ast
+import operator
+from numbers import Real
+from typing import Any, Mapping
+
+
+_BINARY = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.FloorDiv: operator.floordiv,
+    ast.Mod: operator.mod,
+    ast.Pow: operator.pow,
+}
+_UNARY = {
+    ast.Not: operator.not_,
+    ast.UAdd: operator.pos,
+    ast.USub: operator.neg,
+}
+_COMPARE = {
+    ast.Eq: operator.eq,
+    ast.NotEq: operator.ne,
+    ast.Lt: operator.lt,
+    ast.LtE: operator.le,
+    ast.Gt: operator.gt,
+    ast.GtE: operator.ge,
+    ast.In: lambda left, right: left in right,
+    ast.NotIn: lambda left, right: left not in right,
+    ast.Is: operator.is_,
+    ast.IsNot: operator.is_not,
+}
+
+
+def evaluate_expression(expr: str, context: Mapping[str, Any], *, arithmetic_only: bool = False) -> Any:
+    """Interpret literals, names, arithmetic, and optionally comparisons/booleans.
+
+    Calls, attributes, indexing, comprehensions, and arbitrary Python code are
+    outside this language. Unknown names raise ValueError.
+    """
+    try:
+        tree = ast.parse(expr, mode="eval")
+    except SyntaxError as exc:
+        raise ValueError(f"Invalid expression syntax: {exc}") from exc
+
+    def visit(node: ast.AST) -> Any:
+        if isinstance(node, ast.Expression):
+            return visit(node.body)
+        if isinstance(node, ast.Constant):
+            if arithmetic_only and (isinstance(node.value, bool) or not isinstance(node.value, (int, float))):
+                raise ValueError("Arithmetic expressions require numeric literals")
+            return node.value
+        if isinstance(node, ast.Name):
+            if node.id not in context:
+                raise ValueError(f"Unknown expression name: {node.id}")
+            value = context[node.id]
+            if arithmetic_only and not isinstance(value, Real):
+                raise ValueError(f"Arithmetic expression name {node.id} must be numeric")
+            return value
+        if isinstance(node, ast.BinOp) and type(node.op) in _BINARY:
+            return _BINARY[type(node.op)](visit(node.left), visit(node.right))
+        if isinstance(node, ast.UnaryOp) and type(node.op) in _UNARY:
+            if arithmetic_only and isinstance(node.op, ast.Not):
+                raise ValueError("Boolean operations are not allowed in arithmetic expressions")
+            return _UNARY[type(node.op)](visit(node.operand))
+        if not arithmetic_only and isinstance(node, ast.BoolOp):
+            if isinstance(node.op, ast.And):
+                value = True
+                for item in node.values:
+                    value = visit(item)
+                    if not value:
+                        return value
+                return value
+            if isinstance(node.op, ast.Or):
+                value = False
+                for item in node.values:
+                    value = visit(item)
+                    if value:
+                        return value
+                return value
+        if not arithmetic_only and isinstance(node, ast.Compare):
+            left = visit(node.left)
+            for op, comparator in zip(node.ops, node.comparators):
+                operation = _COMPARE.get(type(op))
+                if operation is None:
+                    raise ValueError(f"Expression contains disallowed construct: {type(op).__name__}")
+                right = visit(comparator)
+                if not operation(left, right):
+                    return False
+                left = right
+            return True
+        raise ValueError(f"Expression contains disallowed construct: {type(node).__name__}")
+
+    try:
+        return visit(tree)
+    except ValueError:
+        raise
+    except Exception as exc:
+        raise ValueError(f"Error evaluating expression: {exc}") from exc

{py3plex-2.0.1 → py3plex-2.0.6}/py3plex/algorithms/community_detection/autocommunity_executor.py

@@ -455,6 +455,7 @@ def _evaluate_algorithms(
     from py3plex.algorithms.community_detection.multilayer_quality_metrics import (
         replica_consistency,
         layer_entropy,
+        mdl_score,
     )
     
     import inspect
@@ -519,9 +520,7 @@ def _evaluate_algorithms(
                         value = 0.0
                 
                 elif metric_name == "mdl":
-                    # Description length (if available)
-                    # Placeholder for now
-                    value = 0.0
+                    value = mdl_score(partition, network)
                 
                 elif metric_name == "replica_consistency":
                     # Multilayer coherence metric

{py3plex-2.0.1 → py3plex-2.0.6}/py3plex/algorithms/community_detection/community_louvain.py

@@ -187,7 +187,7 @@ def modularity(partition: Dict, graph: nx.Graph, weight: str = "weight") -> floa
 
     References
     ----------
-    .. 1. Newman, M.E.J. & Girvan, M. Finding and evaluating community
+    [1] Newman, M.E.J. & Girvan, M. Finding and evaluating community
     structure in networks. Physical Review E 69, 26113(2004).
 
     Examples
@@ -274,7 +274,7 @@ def best_partition(
 
     References
     ----------
-    .. 1. Blondel, V.D. et al. Fast unfolding of communities in
+    [1] Blondel, V.D. et al. Fast unfolding of communities in
     large networks. J. Stat. Mech 10008, 1-12(2008).
 
     Examples
@@ -357,7 +357,7 @@ def generate_dendrogram(
 
     References
     ----------
-    .. 1. Blondel, V.D. et al. Fast unfolding of communities in large
+    [1] Blondel, V.D. et al. Fast unfolding of communities in large
     networks. J. Stat. Mech 10008, 1-12(2008).
 
     Examples

{py3plex-2.0.1 → py3plex-2.0.6}/py3plex/algorithms/community_detection/label_propagation.py

@@ -16,8 +16,8 @@ Both algorithms use:
 
 References
 ----------
-.. [1] Label Propagation and Complex Networks (various sources)
-.. [2] Multilayer network community detection literature
+[1] Label Propagation and Complex Networks (various sources)
+[2] Multilayer network community detection literature
 """
 
 from __future__ import annotations
@@ -96,7 +96,7 @@ def multilayer_label_propagation_supra(
     
     Notes
     -----
-    Complexity: O(max_iter * (|E| + omega * L * |V|)) where E is edges, L layers, V nodes
+    Complexity: O(max_iter * (\\|E\\| + omega * L * \\|V\\|)) where E is edges, L layers, V nodes
     """
     # Validate parameters
     if omega < 0:
@@ -331,7 +331,7 @@ def multiplex_label_propagation_consensus(
     
     Notes
     -----
-    Complexity: O(max_iter * inner_max_iter * |E|) where E is edges
+    Complexity: O(max_iter * inner_max_iter * \\|E\\|) where E is edges
     """
     # Validate parameters
     if max_iter < 1:

py3plex-2.0.6/py3plex/algorithms/community_detection/mdl_benchmark.py

@@ -0,0 +1,353 @@
+"""
+MDL Metric Benchmark on Synthetic Multilayer LFR Graphs.
+
+Unit tests (see ``tests/test_mdl_score.py``) check that ``mdl_score`` behaves
+correctly on hand-built toy graphs, but they cannot show that the metric is
+actually a *useful* community-quality signal. This module answers that with
+an empirical benchmark against known ground truth:
+
+- Generate multilayer LFR graphs across a range of mixing parameters ``mu``
+  (easy -> hard).
+- On each graph, score three partitions -- the ground truth, a corrupted/
+  degenerate partition, and the output of a real algorithm (Louvain) -- with
+  ``mdl_score`` and the baseline metrics ``multilayer_modularity`` and
+  ``replica_consistency``.
+- Check whether ``mdl_score`` ranks ground truth best as ``mu`` grows, how
+  its ranking agrees (or informatively disagrees) with modularity's, and how
+  its compute cost compares to the baselines' on the same graphs.
+
+Algorithm choice: this uses ``community_louvain.best_partition`` (run on the
+flat supra-graph, i.e. treating each ``(node, layer)`` pair as an opaque
+node id) rather than this package's own ``leiden_multilayer``/
+``louvain_multilayer``. Both of the latter are single-level greedy local
+search with no hierarchical aggregation/coarsening phase, so they reliably
+get stuck in a poor local optimum on anything past toy-sized graphs
+(confirmed by hand-stepping the local-move loop -- e.g. on a 2-layer,
+2-clique graph with default interlayer coupling they converge to a
+half-merged partition with modularity 0.03 instead of the true ~0.5).
+``community_louvain.best_partition`` implements the real multi-level
+Louvain (with ``generate_dendrogram``/``induced_graph`` aggregation) and
+was verified to recover ground-truth-comparable modularity on the LFR
+graphs here; that upstream local-optimum issue is a separate, unrelated bug
+worth fixing on its own.
+"""
+
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Any, Dict, List, Sequence, Tuple
+import time
+import warnings
+
+import numpy as np
+from scipy.stats import spearmanr
+
+from py3plex.algorithms.community_detection.community_louvain import (
+    best_partition,
+)
+from py3plex.algorithms.community_detection.multilayer_benchmark import (
+    generate_multilayer_lfr,
+)
+from py3plex.algorithms.community_detection.multilayer_modularity import (
+    multilayer_modularity,
+)
+from py3plex.algorithms.community_detection.multilayer_quality_metrics import (
+    mdl_score,
+    replica_consistency,
+)
+
+NodeLayer = Tuple[Any, Any]
+Partition = Dict[NodeLayer, int]
+
+
+@dataclass
+class PartitionScore:
+    """Scores for one (mu, seed, partition_type) combination."""
+
+    mu: float
+    seed: int
+    n_nodes: int
+    n_edges: int
+    partition_type: str  # "ground_truth" | "corrupted" | "louvain"
+    mdl: float
+    modularity: float
+    replica_consistency: float
+    mdl_time_s: float
+    modularity_time_s: float
+    rc_time_s: float
+
+
+def _flatten_ground_truth(communities: Dict[NodeLayer, set]) -> Partition:
+    """Collapse each node-layer's community *set* to one representative label.
+
+    ``generate_multilayer_lfr`` returns overlapping-community sets; with the
+    default ``overlapping_nodes=0`` every set is a singleton, so taking the
+    min element is a lossless, deterministic flattening to the plain
+    ``(node, layer) -> community_id`` format ``mdl_score``/``multilayer_modularity``/
+    ``replica_consistency`` all expect.
+    """
+    return {node_layer: min(coms) for node_layer, coms in communities.items()}
+
+
+def _corrupt_partition(
+    partition: Partition, corruption_rate: float, seed: int
+) -> Partition:
+    """Randomly reassign a fraction of node-layer pairs to a different label.
+
+    A stand-in for a "degenerate" partition: same node coverage and label
+    vocabulary as the input, but a chunk of nodes scattered into the wrong
+    community.
+    """
+    rng = np.random.RandomState(seed)
+    labels = sorted(set(partition.values()))
+    keys = list(partition.keys())
+    n_corrupt = int(len(keys) * corruption_rate)
+    corrupt_idx = rng.choice(len(keys), size=n_corrupt, replace=False)
+
+    corrupted = dict(partition)
+    for idx in corrupt_idx:
+        key = keys[idx]
+        current = corrupted[key]
+        choices = [label for label in labels if label != current] or labels
+        corrupted[key] = rng.choice(choices)
+    return corrupted
+
+
+def _louvain_partition(network: Any, resolution: float) -> Partition:
+    """Run real multi-level Louvain on the flat supra-graph.
+
+    ``network.core_network`` already has ``(node, layer)`` tuples as node
+    ids, so ``best_partition`` naturally treats each node-layer pair as its
+    own unit -- this is what makes it usable as a multilayer "real
+    algorithm" partition without any extra flattening/expansion step.
+    """
+    return best_partition(network.core_network, resolution=resolution)
+
+
+def _score_partition(
+    partition: Partition, network: Any
+) -> Tuple[float, float, float, float, float, float]:
+    """Return (mdl, modularity, replica_consistency, mdl_s, modularity_s, rc_s)."""
+    t0 = time.perf_counter()
+    with warnings.catch_warnings():
+        # mdl_score warns on partial/parallel/weighted inputs; none of that
+        # is a bug here, so it would just be report noise.
+        warnings.simplefilter("ignore")
+        mdl = mdl_score(partition, network)
+    t1 = time.perf_counter()
+
+    mod = multilayer_modularity(network, partition)
+    t2 = time.perf_counter()
+
+    rc = replica_consistency(partition, network)
+    t3 = time.perf_counter()
+
+    return mdl, mod, rc, (t1 - t0), (t2 - t1), (t3 - t2)
+
+
+def run_benchmark(
+    mu_values: Sequence[float] = (0.05, 0.1, 0.2, 0.3, 0.4, 0.5),
+    ns: Sequence[int] = (200,),
+    layers: Sequence[str] = ("L1", "L2", "L3"),
+    avg_degree: float = 10.0,
+    min_community: int = 20,
+    seeds: Sequence[int] = (0, 1, 2),
+    corruption_rate: float = 0.3,
+    resolution: float = 1.0,
+) -> List[PartitionScore]:
+    """Score ground-truth/corrupted/Louvain partitions across an LFR ``mu`` sweep.
+
+    Args:
+        mu_values: LFR mixing parameters to sweep (0 = perfect communities,
+            1 = random -- i.e. easy to hard).
+        ns: Graph sizes (node counts) to sweep. Pass more than one value to
+            get a scaling curve for metric compute cost.
+        layers: Layer names for the generated multiplex graph.
+        avg_degree: Average per-layer degree passed to ``generate_multilayer_lfr``.
+        min_community: Minimum community size passed to ``generate_multilayer_lfr``.
+        seeds: Random seeds; each is used both for graph generation and for
+            the corrupted-partition randomness, so results are reproducible
+            per (mu, n, seed).
+        corruption_rate: Fraction of node-layer pairs reassigned to a wrong
+            community in the corrupted partition.
+        resolution: Passed to ``community_louvain.best_partition``.
+
+    Returns:
+        One ``PartitionScore`` per (mu, n, seed, partition_type) combination.
+    """
+    records: List[PartitionScore] = []
+
+    for n in ns:
+        for mu in mu_values:
+            for seed in seeds:
+                network, gt_sets = generate_multilayer_lfr(
+                    n=n,
+                    layers=list(layers),
+                    mu=mu,
+                    avg_degree=avg_degree,
+                    min_community=min_community,
+                    seed=seed,
+                )
+                ground_truth = _flatten_ground_truth(gt_sets)
+                n_nodes = network.core_network.number_of_nodes()
+                n_edges = network.core_network.number_of_edges()
+
+                partitions: Dict[str, Partition] = {
+                    "ground_truth": ground_truth,
+                    "corrupted": _corrupt_partition(
+                        ground_truth, corruption_rate, seed
+                    ),
+                    "louvain": _louvain_partition(network, resolution),
+                }
+
+                for partition_type, partition in partitions.items():
+                    mdl, mod, rc, t_mdl, t_mod, t_rc = _score_partition(
+                        partition, network
+                    )
+                    records.append(
+                        PartitionScore(
+                            mu=mu,
+                            seed=seed,
+                            n_nodes=n_nodes,
+                            n_edges=n_edges,
+                            partition_type=partition_type,
+                            mdl=mdl,
+                            modularity=mod,
+                            replica_consistency=rc,
+                            mdl_time_s=t_mdl,
+                            modularity_time_s=t_mod,
+                            rc_time_s=t_rc,
+                        )
+                    )
+
+    return records
+
+
+def ranking_agreement_report(records: List[PartitionScore]) -> Dict[str, Any]:
+    """Check whether ``mdl_score`` ranks ground truth best, and agrees with modularity.
+
+    Returns:
+        Dict with:
+        - ``ground_truth_best_rate``: fraction of (mu, n, seed) groups where
+          ground truth got the lowest (best) MDL score among the three
+          partitions.
+        - ``mean_spearman_by_mu``: mean Spearman correlation, per ``mu``,
+          between the MDL ranking and the modularity ranking of the three
+          partitions in each group (1.0 = full agreement, negative = MDL
+          flags something modularity doesn't).
+        - ``disagreements``: groups where MDL and modularity disagree on
+          which partition is best -- the interesting case where MDL might be
+          catching a degenerate partition that modularity misses.
+    """
+    groups: Dict[Tuple[float, int, int], List[PartitionScore]] = defaultdict(list)
+    for r in records:
+        groups[(r.mu, r.n_nodes, r.seed)].append(r)
+
+    gt_best_count = 0
+    spearman_per_mu: Dict[float, List[float]] = defaultdict(list)
+    disagreements: List[Dict[str, Any]] = []
+
+    for (mu, n_nodes, seed), group in groups.items():
+        by_type = {r.partition_type: r for r in group}
+        mdl_vals = [r.mdl for r in group]
+        if by_type["ground_truth"].mdl == min(mdl_vals):
+            gt_best_count += 1
+
+        if len(group) >= 2:
+            # Lower MDL = better; higher modularity = better, so negate
+            # modularity to compare both rankings in the same direction.
+            rho, _ = spearmanr(
+                [r.mdl for r in group], [-r.modularity for r in group]
+            )
+            spearman_per_mu[mu].append(rho)
+
+        mdl_best = min(group, key=lambda r: r.mdl).partition_type
+        mod_best = max(group, key=lambda r: r.modularity).partition_type
+        if mdl_best != mod_best:
+            disagreements.append(
+                {
+                    "mu": mu,
+                    "n_nodes": n_nodes,
+                    "seed": seed,
+                    "mdl_best": mdl_best,
+                    "modularity_best": mod_best,
+                    "scores": {
+                        r.partition_type: {
+                            "mdl": r.mdl,
+                            "modularity": r.modularity,
+                        }
+                        for r in group
+                    },
+                }
+            )
+
+    n_groups = len(groups)
+    return {
+        "ground_truth_best_rate": gt_best_count / n_groups if n_groups else float("nan"),
+        "mean_spearman_by_mu": {
+            mu: float(np.nanmean(vals)) for mu, vals in sorted(spearman_per_mu.items())
+        },
+        "disagreements": disagreements,
+    }
+
+
+def scaling_report(records: List[PartitionScore]) -> Dict[int, Dict[str, float]]:
+    """Average per-metric compute time (seconds), grouped by graph size."""
+    by_size: Dict[int, Dict[str, List[float]]] = defaultdict(lambda: defaultdict(list))
+    for r in records:
+        by_size[r.n_nodes]["mdl_score"].append(r.mdl_time_s)
+        by_size[r.n_nodes]["multilayer_modularity"].append(r.modularity_time_s)
+        by_size[r.n_nodes]["replica_consistency"].append(r.rc_time_s)
+
+    return {
+        n_nodes: {metric: float(np.mean(times)) for metric, times in metrics.items()}
+        for n_nodes, metrics in sorted(by_size.items())
+    }
+
+
+def print_report(records: List[PartitionScore]) -> None:
+    """Print a human-readable summary: ranking agreement + scaling."""
+    ranking = ranking_agreement_report(records)
+    scaling = scaling_report(records)
+
+    print("=" * 72)
+    print("MDL METRIC BENCHMARK REPORT")
+    print("=" * 72)
+
+    print(
+        f"\nGround truth ranked best (lowest MDL) in "
+        f"{ranking['ground_truth_best_rate']:.1%} of (mu, n, seed) groups"
+    )
+
+    print("\nMDL vs. modularity ranking agreement (Spearman rho) by mu:")
+    for mu, rho in ranking["mean_spearman_by_mu"].items():
+        print(f"  mu={mu:.2f}: rho={rho:+.3f}")
+
+    if ranking["disagreements"]:
+        print(
+            f"\n{len(ranking['disagreements'])} group(s) where MDL and "
+            "modularity pick a different 'best' partition:"
+        )
+        for d in ranking["disagreements"]:
+            print(
+                f"  mu={d['mu']:.2f} n={d['n_nodes']} seed={d['seed']}: "
+                f"mdl picks '{d['mdl_best']}', modularity picks "
+                f"'{d['modularity_best']}'"
+            )
+    else:
+        print("\nNo disagreements between MDL's and modularity's top pick.")
+
+    print("\nMean metric compute time (seconds) by graph size:")
+    header = f"  {'n_nodes':>10} {'mdl_score':>12} {'modularity':>12} {'replica_consistency':>20}"
+    print(header)
+    for n_nodes, metrics in scaling.items():
+        print(
+            f"  {n_nodes:>10} {metrics['mdl_score']:>12.4f} "
+            f"{metrics['multilayer_modularity']:>12.4f} "
+            f"{metrics['replica_consistency']:>20.4f}"
+        )
+    print("=" * 72)
+
+
+if __name__ == "__main__":
+    results = run_benchmark()
+    print_report(results)