Refine configuration model API and docs

Author: FraLotito

docs/quickstart.rst

@@ -112,6 +112,30 @@ Projections and matrices
    A = adjacency_matrix(hg)
    G = clique_projection(hg)
 
+Configuration model
+-------------------
+
+Use ``configuration_model`` to randomize a hypergraph with a
+configuration-model-style MCMC sampler.
+
+.. code-block:: python
+
+   from hypergraphx.generation import configuration_model
+
+   hg_rand = configuration_model(hg, n_steps=500, label="edge", seed=0)
+
+The ``duplicate_output`` parameter controls how repeated sampled hyperedges are
+handled:
+
+- ``"merge"`` (default): collapse duplicates into a simple hypergraph
+- ``"count"``: return a weighted hypergraph whose edge weights equal sampled multiplicities
+- ``"error"``: raise an error if repeated sampled hyperedges occur
+
+.. code-block:: python
+
+   hg_rand = configuration_model(hg, n_steps=500, duplicate_output="merge", seed=0)
+   hg_counts = configuration_model(hg, n_steps=500, duplicate_output="count", seed=0)
+
 Measures
 --------
 

hypergraphx/generation/configuration_model.py

@@ -8,34 +8,79 @@
 from hypergraphx.generation._rng import np_rng, split_seed
 
 
+def _build_hypergraph_from_sampled_edges(
+    edges,
+    *,
+    duplicate_output="merge",
+    weighted_output=False,
+):
+    edge_counts = Counter(tuple(sorted(edge)) for edge in edges)
+    generated_edges = list(edge_counts.keys())
+
+    if duplicate_output == "merge":
+        new_h = Hypergraph(weighted=weighted_output)
+        if weighted_output:
+            new_h.add_edges(generated_edges, weights=[1] * len(generated_edges))
+        else:
+            new_h.add_edges(generated_edges)
+        return new_h
+
+    if duplicate_output == "count":
+        new_h = Hypergraph(weighted=True)
+        new_h.add_edges(
+            generated_edges, weights=[edge_counts[edge] for edge in generated_edges]
+        )
+        return new_h
+
+    if duplicate_output == "error":
+        repeated_edges = [edge for edge, count in edge_counts.items() if count > 1]
+        if repeated_edges:
+            raise InvalidParameterError(
+                "Repeated sampled hyperedges are not allowed when "
+                "duplicate_output='error'."
+            )
+        new_h = Hypergraph(weighted=weighted_output)
+        if weighted_output:
+            new_h.add_edges(generated_edges, weights=[1] * len(generated_edges))
+        else:
+            new_h.add_edges(generated_edges)
+        return new_h
+
+    raise InvalidParameterError(
+        "duplicate_output must be one of: 'merge', 'count', 'error'."
+    )
+
+
 def _cm_MCMC(
     hypergraph,
     n_steps=1000,
     label="edge",
     n_clash=1,
-    detailed=True,
+    restrict_to_same_size=True,
+    duplicate_output="merge",
     *,
     seed: int | None = None,
 ):
     """
     Conduct Markov Chain Monte Carlo in order to approximately
     sample from the space of appropriately-labeled graphs.
     n_steps: number of steps to perform
-    label: the label space to use. Can take values in ['vertex' , 'stub', 'edge'].
+    label: the label space to use. Can take values in ['vertex', 'edge'].
     n_clash: the number of clashes permitted when updating the edge counts in vertex-labeled MH.
         n_clash = 0 will be exact but very slow.
         n_clash >= 2 may lead to performance gains at the cost of decreased accuracy.
-    detailed: if True, preserve the number of edges of given dimension incident to each node
+    restrict_to_same_size: if True, only rewire pairs of hyperedges with the same size
+    duplicate_output: controls how repeated sampled hyperedges are handled
     """
     rng = np_rng(seed)
 
     def proposal_generator(m):
-        # Propose a transition in stub- and edge-labeled MH.
+        # Propose a transition in edge-labeled MH.
 
         def __proposal(edge_list):
             i, j = rng.integers(0, m, 2)
             f1, f2 = edge_list[i], edge_list[j]
-            if detailed:
+            if restrict_to_same_size:
                 while len(f1) != len(f2):
                     i, j = rng.integers(0, m, 2)
                     f1, f2 = edge_list[i], edge_list[j]
@@ -73,7 +118,7 @@ def __pairwise_reshuffle(f1, f2):
             logger.debug("%s %s %s %s", f1, f2, g1, g2)
         return tuple(sorted(g1)), tuple(sorted(g2))
 
-    def stub_edge_mh(message=True):
+    def edge_mh(message=True):
         mh_rounds = 0
         mh_steps = 0
         c_new = [list(c) for c in hypergraph.get_edges()]
@@ -92,10 +137,11 @@ def mh_step():
             mh_step()
             n += 1
 
-        new_h = Hypergraph()
-        # check this behavior
-        generated_edges = list(set([tuple(sorted(f)) for f in c_new]))
-        new_h.add_edges(generated_edges)
+        new_h = _build_hypergraph_from_sampled_edges(
+            c_new,
+            duplicate_output=duplicate_output,
+            weighted_output=hypergraph.is_weighted(),
+        )
         mh_steps += n
         mh_rounds += 1
 
@@ -149,7 +195,7 @@ def vertex_labeled_mh(message=True):
                     i, j = (ij[k_], ij[k_ + 1])
                     k_ += 2
                     f1, f2 = l[i], l[j]
-                if detailed:
+                if restrict_to_same_size:
                     while len(f1) != len(f2):
                         i, j = (ij[k_], ij[k_ + 1])
                         k_ += 2
@@ -190,18 +236,20 @@ def vertex_labeled_mh(message=True):
                 n_rejected,
             )
 
-        new_h = Hypergraph()
-        new_h.add_edges([tuple(sorted(f)) for f in list(c.elements())])
+        new_h = _build_hypergraph_from_sampled_edges(
+            list(c.elements()),
+            duplicate_output=duplicate_output,
+            weighted_output=hypergraph.is_weighted(),
+        )
         mh_steps += k - n_rejected
         mh_rounds += 1
         return new_h
 
-    if (label == "edge") or (label == "stub"):
-        return stub_edge_mh()
+    if label == "edge":
+        return edge_mh()
     elif label == "vertex":
         return vertex_labeled_mh()
-    else:
-        logging.getLogger(__name__).warning("Not implemented")
+    raise InvalidParameterError("label must be one of: 'edge', 'vertex'.")
 
 
 def configuration_model(
@@ -211,34 +259,99 @@ def configuration_model(
     order=None,
     size=None,
     n_clash=1,
-    detailed=True,
+    restrict_to_same_size=True,
+    duplicate_output="merge",
     seed: int | None = None,
 ):
     """
     Sample a randomized hypergraph using a configuration-model-style MCMC.
 
-    Parameters are largely legacy; the key UX improvements are:
-    - `seed=` controls the RNG (reproducible, does not rely on global `np.random.seed`)
-    - when `order`/`size` is provided, only that size class is rewired
+    The sampler supports two labeling conventions:
+
+    - ``label="edge"``: rewires pairs of hyperedges directly.
+    - ``label="vertex"``: samples in the space of vertex-labeled hypergraphs
+      using a collision-controlled update scheme.
+
+    By default, all hyperedges are eligible for rewiring. If ``order`` or
+    ``size`` is specified, only hyperedges of the selected size are rewired and
+    all other hyperedges are copied unchanged into the output hypergraph.
+
+    Parameters
+    ----------
+    hypergraph : Hypergraph
+        Input hypergraph to randomize.
+    n_steps : int, default=1000
+        Number of MCMC update steps.
+    label : {"edge", "vertex"}, default="edge"
+        Labeling convention used by the sampler.
+    order : int, optional
+        Hyperedge order to rewire. If provided, only hyperedges of size
+        ``order + 1`` are randomized.
+    size : int, optional
+        Hyperedge size to rewire. Mutually exclusive with ``order``.
+    n_clash : int, default=1
+        Collision threshold used in the vertex-labeled sampler. Only relevant
+        when ``label="vertex"``.
+    restrict_to_same_size : bool, default=True
+        If ``True``, proposals are restricted to pairs of hyperedges with the
+        same size, so rewiring is performed within size classes.
+    duplicate_output : {"merge", "count", "error"}, default="merge"
+        Controls how repeated sampled hyperedges are handled in the returned
+        object. ``"merge"`` collapses duplicates into a simple hypergraph,
+        ``"count"`` encodes multiplicities as edge weights, and ``"error"``
+        raises if repeated sampled hyperedges occur.
+    seed : int, optional
+        Seed for the random number generator.
+
+    Returns
+    -------
+    Hypergraph
+        Randomized hypergraph.
+
+    Raises
+    ------
+    InvalidParameterError
+        If both ``order`` and ``size`` are specified.
+    InvalidParameterError
+        If ``label`` is not one of ``"edge"`` or ``"vertex"``.
+    InvalidParameterError
+        If ``duplicate_output="count"`` is used with a weighted input
+        hypergraph.
+
+    Notes
+    -----
+    In the size-restricted mode, the function first extracts the corresponding
+    subhypergraph, randomizes it, and then reinserts the untouched hyperedges.
+    The default ``duplicate_output="merge"`` returns a simple hypergraph and
+    collapses repeated sampled hyperedges.
 
     Examples
     --------
     >>> from hypergraphx import Hypergraph
     >>> from hypergraphx.generation import configuration_model
     >>> H = Hypergraph(edge_list=[(0, 1), (1, 2), (0, 1, 2)], weighted=False)
     >>> H2 = configuration_model(H, n_steps=10, label="edge", seed=0)
-    >>> H.num_edges() == H2.num_edges()
+    >>> isinstance(H2, Hypergraph)
+    True
+
+    >>> H3 = configuration_model(H, n_steps=10, seed=0, duplicate_output="count")
+    >>> H3.is_weighted()
     True
     """
     if order is not None and size is not None:
         raise InvalidParameterError("Only one of order and size can be specified.")
+    if duplicate_output == "count" and hypergraph.is_weighted():
+        raise InvalidParameterError(
+            "duplicate_output='count' is only supported for unweighted hypergraphs."
+        )
     if order is None and size is None:
         return _cm_MCMC(
             hypergraph,
             n_steps=n_steps,
             label=label,
             n_clash=n_clash,
-            detailed=detailed,
+            restrict_to_same_size=restrict_to_same_size,
+            duplicate_output=duplicate_output,
             seed=seed,
         )
 
@@ -256,10 +369,15 @@ def configuration_model(
         n_steps=n_steps,
         label=label,
         n_clash=n_clash,
-        detailed=detailed,
+        restrict_to_same_size=restrict_to_same_size,
+        duplicate_output=duplicate_output,
         seed=sub_seed,
     )
     for e in hypergraph.get_edges():
         if len(e) != size:
-            shuffled.add_edge(e)
+            if shuffled.is_weighted():
+                weight = hypergraph.get_weight(e) if hypergraph.is_weighted() else 1
+                shuffled.add_edge(e, weight=weight)
+            else:
+                shuffled.add_edge(e)
     return shuffled

hypergraphx/motifs/motifs.py

@@ -91,7 +91,7 @@ def _motifs_order_4(edges):
     for i in range(ROUNDS):
         logger.info("Computing config model motifs of order %s. Step: %s", order, i + 1)
         sub_seed = int(rng.integers(0, 2**32 - 1, dtype=np.uint32))
-        e1 = configuration_model(hypergraph, label="stub", n_steps=STEPS, seed=sub_seed)
+        e1 = configuration_model(hypergraph, label="edge", n_steps=STEPS, seed=sub_seed)
         if order == 3:
             m1 = _motifs_order_3(e1.get_edges())
         elif order == 4:

tests/generation/test_configuration_model.py

@@ -2,6 +2,7 @@
 import pytest
 
 from hypergraphx import Hypergraph
+from hypergraphx.exceptions import InvalidParameterError
 from hypergraphx.generation.configuration_model import configuration_model
 
 
@@ -35,3 +36,53 @@ def test_configuration_model_invalid_args():
     hg = _make_hypergraph()
     with pytest.raises(ValueError, match="Only one"):
         configuration_model(hg, order=1, size=2)
+
+
+def test_configuration_model_rejects_stub_label():
+    """Test configuration model rejects the removed stub label."""
+    hg = _make_hypergraph()
+    with pytest.raises(InvalidParameterError, match="label must be one of"):
+        configuration_model(hg, label="stub")
+
+
+def test_configuration_model_duplicate_output_merge_default():
+    """Test repeated sampled hyperedges are merged by default."""
+    hg = Hypergraph(edge_list=[(0, 1), (2, 3), (0, 2), (1, 3)], weighted=False)
+
+    sampled = configuration_model(hg, n_steps=50, label="edge", seed=6)
+
+    assert not sampled.is_weighted()
+    assert sampled.num_edges() == 2
+    assert set(sampled.get_edges()) == {(0, 2), (1, 3)}
+
+
+def test_configuration_model_duplicate_output_count():
+    """Test repeated sampled hyperedges can be encoded as weights."""
+    hg = Hypergraph(edge_list=[(0, 1), (2, 3), (0, 2), (1, 3)], weighted=False)
+
+    sampled = configuration_model(
+        hg, n_steps=50, label="edge", seed=6, duplicate_output="count"
+    )
+
+    assert sampled.is_weighted()
+    assert sampled.num_edges() == 2
+    assert sampled.get_weight((0, 2)) == 2
+    assert sampled.get_weight((1, 3)) == 2
+
+
+def test_configuration_model_duplicate_output_error():
+    """Test repeated sampled hyperedges can be rejected."""
+    hg = Hypergraph(edge_list=[(0, 1), (2, 3), (0, 2), (1, 3)], weighted=False)
+
+    with pytest.raises(InvalidParameterError, match="Repeated sampled hyperedges"):
+        configuration_model(
+            hg, n_steps=50, label="edge", seed=6, duplicate_output="error"
+        )
+
+
+def test_configuration_model_duplicate_output_count_rejects_weighted_input():
+    """Test multiplicity-as-weight output is rejected for weighted inputs."""
+    hg = Hypergraph(edge_list=[(0, 1), (1, 2)], weighted=True, weights=[2.0, 3.0])
+
+    with pytest.raises(InvalidParameterError, match="only supported for unweighted"):
+        configuration_model(hg, n_steps=5, duplicate_output="count", seed=0)