xgi.generators.random#

Generate random (non-uniform) hypergraphs.

Functions

chung_lu_hypergraph(k1, k2, seed=None)#

A function to generate a Chung-Lu hypergraph

Parameters:

  • k1 (dictionary) – Dictionary where the keys are node ids and the values are node degrees.

  • k2 (dictionary) – Dictionary where the keys are edge ids and the values are edge sizes.

  • seed (int, numpy.random.Generator, or None, optional) – The seed for the random number generator. By default, None.

Returns:

The generated hypergraph

Return type:

Hypergraph object

Warns:

warnings.warn – If the sums of the edge sizes and node degrees are not equal, the algorithm still runs, but raises a warning.

Notes

The sums of k1 and k2 should be the same. If they are not the same, this function returns a warning but still runs.

References

Implemented by Mirah Shi in HyperNetX and described for bipartite networks by Aksoy et al. in https://doi.org/10.1093/comnet/cnx001

Example

>>> import xgi
>>> import random
>>> n = 100
>>> k1 = {i : random.randint(1, 100) for i in range(n)}
>>> k2 = {i : sorted(k1.values())[i] for i in range(n)}
>>> H = xgi.chung_lu_hypergraph(k1, k2)
dcsbm_hypergraph(k1, k2, g1, g2, omega, seed=None)#

A function to generate a Degree-Corrected Stochastic Block Model (DCSBM) hypergraph.

Parameters:

  • k1 (dict) – This is a dictionary where the keys are node ids and the values are node degrees.

  • k2 (dict) – This is a dictionary where the keys are edge ids and the values are edge sizes.

  • g1 (dict) – This a dictionary where the keys are node ids and the values are the group ids to which the node belongs. The keys must match the keys of k1.

  • g2 (dict) – This a dictionary where the keys are edge ids and the values are the group ids to which the edge belongs. The keys must match the keys of k2.

  • omega (2D numpy array) – This is a matrix with entries which specify the number of edges between a given node community and edge community. The number of rows must match the number of node communities and the number of columns must match the number of edge communities.

  • seed (int, numpy.random.Generator, or None, optional) – The seed for the random number generator. By default, None.

Return type:

Hypergraph

Warns:

warnings.warn – If the sums of the edge sizes and node degrees are not equal, the algorithm still runs, but raises a warning. Also if the sum of the omega matrix does not match the sum of degrees, a warning is raised.

Notes

The sums of k1 and k2 should be the same. If they are not the same, this function returns a warning but still runs. The sum of k1 (and k2) and omega should be the same. If they are not the same, this function returns a warning but still runs and the number of entries in the incidence matrix is determined by the omega matrix.

References

Implemented by Mirah Shi in HyperNetX and described for bipartite networks by Larremore et al. in https://doi.org/10.1103/PhysRevE.90.012805

Examples

>>> import xgi; import random; import numpy as np
>>> n = 50
>>> k1 = {i : random.randint(1, n) for i in range(n)}
>>> k2 = {i : sorted(k1.values())[i] for i in range(n)}
>>> g1 = {i : random.choice([0, 1]) for i in range(n)}
>>> g2 = {i : random.choice([0, 1]) for i in range(n)}
>>> omega = np.array([[n//2, 10], [10, n//2]])
>>> # H = xgi.dcsbm_hypergraph(k1, k2, g1, g2, omega)
fast_random_hypergraph(n, ps, order=None, seed=None)#

Generates a random hypergraph with a fast algorithm.

Generate n nodes, and connect any d+1 nodes by a hyperedge with probability ps[d-1].

This uses a fast method for generating hyperedges. See the references for more details.

Parameters:

  • n (int) – Number of nodes

  • ps (list of float, or float) – List of probabilities (between 0 and 1) to create a hyperedge at each order d between any d+1 nodes (when order is None). For example, ps[0] is the wiring probability of any edge (2 nodes), ps[1] of any triangles (3 nodes). If a float, generate a uniform hypergraph. See order for advanced options when it is not None.

  • order (int, list of ints, or array of ints or None (default)) – If None (default), ignored. If list or array, generates a hypergraph with edges of orders order[0], order[1], etc. (The length of ps must match the length of order in this case).

  • seed (int, numpy.random.Generator, or None, optional) – The seed for the random number generator. By default, None.

Returns:

The generated hypergraph

Return type:

Hypergraph object

References

M. Dewar et al. “Subhypergraphs in non-uniform random hypergraphs” https://arxiv.org/abs/1703.07686

Nicholas W. Landry and Juan G. Restrepo, “Opinion disparity in hypergraphs with community structure”, Phys. Rev. E 108, 034311 (2024). https://doi.org/10.1103/PhysRevE.108.034311

See also

random_hypergraph

Example

>>> import xgi
>>> H = xgi.fast_random_hypergraph(50, [0.1, 0.01])
random_nested_hypergraph(n, m, d, epsilon, seed=None)#

A function to generate a random nested hypergraph.

Parameters:

  • n (int) – Number of nodes.

  • m (int) – Number of facets.

  • d (int) – Size of each facet.

  • epsilon (float or list of float) – Retention probability. If a float, the same retention probability is used for all sub-facet sizes. If a list, epsilon[i] is the retention probability for hyperedges of size i+2, for i = 0, ..., d-3. Hyperedges of size t are rewired with probability 1 - epsilon[t-2].

  • seed (int, numpy.random.Generator, or None, optional) – The seed for the random number generator. By default, None.

Returns:

The generated hypergraph

Return type:

Hypergraph object

Notes

The algorithm proceeds as follows:

  1. Generate m facets of size d by uniform random node assignment, rejecting exact duplicate facets.

  2. For each facet, enumerate all proper subsets of sizes 2 through d − 1 (singletons excluded). Together with the facets themselves, these form the initial edge set. Duplicates across facets are removed.

  3. For each hyperedge of size t < d: with probability 1 − epsilon[t-2], rewire the edge by picking one pivot node uniformly at random from the edge and replacing the other t − 1 nodes with nodes sampled uniformly from {0, …, n − 1}.

The nestedness is controlled primarily by epsilon: larger values preserve more induced subedges and therefore produce more nested hypergraphs, with epsilon=1 yielding a fully nested construction and epsilon=0 rewiring every non-facet edge. If epsilon is a list, it tunes nestedness separately for each subedge size.

References

Jihye Kim, Deok-Sun Lee, and K-I. Goh, “Contagion dynamics on hypergraphs with nested hyperedges”, Phys. Rev. E 108, 034313 (2023). https://doi.org/10.1103/PhysRevE.108.034313

Example

>>> import xgi
>>> H = xgi.random_nested_hypergraph(20, 5, 4, 0.8)
random_hypergraph(n, ps, order=None, seed=None)#

Generates a random hypergraph

Generate N nodes, and connect any d+1 nodes by a hyperedge with probability ps[d-1].

Parameters:

  • n (int) – Number of nodes

  • ps (list of float, or float) – List of probabilities (between 0 and 1) to create a hyperedge at each order d between any d+1 nodes (when order is None). For example, ps[0] is the wiring probability of any edge (2 nodes), ps[1] of any triangles (3 nodes). If a float, generate a uniform hypergraph (in this case, order must be specified) See order for advanced options when it is not None.

  • order (int, list of ints, or array of ints or None (default)) – If None, ignore. If list or array, generates a hypergraph with edges of orders order[0], order[1], etc. (The length of ps must match the length of order in this case).

  • seed (int, numpy.random.Generator, or None, optional) – The seed for the random number generator. By default, None.

Returns:

The generated hypergraph

Return type:

Hypergraph object

References

Described as ‘random hypergraph’ by M. Dewar et al. in https://arxiv.org/abs/1703.07686

Warns:

warnings.warn – Because fast_random_hypergraph is a much faster method for generating random hypergraphs.

See also

fast_random_hypergraph

Example

>>> import xgi
>>> H = xgi.random_hypergraph(50, [0.1, 0.01])
simplicial_chung_lu_hypergraph(k1, k2, p, seed=None)#

A function to generate a simplicial Chung-Lu hypergraph.

Parameters:

  • k1 (dictionary) – Dictionary where the keys are node ids and the values are node degrees.

  • k2 (dictionary) – Dictionary where the keys are edge ids and the values are edge sizes.

  • p (float) – Probability (between 0 and 1) of generating a simplicial edge instead of a Chung-Lu edge. Controls the amount of nestedness.

  • seed (int, numpy.random.Generator, or None, optional) – The seed for the random number generator. By default, None.

Returns:

The generated hypergraph

Return type:

Hypergraph object

Warns:

warnings.warn – If the sums of the edge sizes and node degrees are not equal, the algorithm still runs, but raises a warning.

Notes

The sums of k1 and k2 should be the same. If they are not the same, this function returns a warning but still runs.

References

Jordan Barrett, Paweł Prałat, Aaron Smith, and François Théberge, “Counting simplicial pairs in hypergraphs”, J. Complex Netw. 13, cnaf021 (2025). https://doi.org/10.1093/comnet/cnaf021

See also

chung_lu_hypergraph

Example

>>> import xgi
>>> import numpy as np
>>> n = 50
>>> rng = np.random.default_rng(0)
>>> k1 = {i : rng.integers(1, 11) for i in range(n)}
>>> k2 = {i : sorted(k1.values())[i] for i in range(n)}
>>> H = xgi.simplicial_chung_lu_hypergraph(k1, k2, p=0.5)
watts_strogatz_hypergraph(n, d, k, l, p, seed=None)#

Generates a Watts-Strogatz hypergraph

Parameters:

  • n (int) – Number of nodes

  • d (int) – Edge size

  • k (int) – Number of edges of which a node is a part. Should be a multiple of 2.

  • l (int) – Overlap between edges

  • p (float) – The rewiring probability

  • seed (int, numpy.random.Generator, or None, optional) – The seed for the random number generator. By default, None.

Returns:

THe Watts-Strogatz hypergraph

Return type:

xgi.Hypergraph

See also

ring_lattice

References

Tanu Raghav, Stefano Boccaletti, and Sarika Jalan, Smallworldness in hypergraphs, https://doi.org/10.1088/2632-072X/acf430