xgi.generators.random#

Generate random (non-uniform) hypergraphs.

Functions

chung_lu_hypergraph(k1, k2, seed=None)[source]#

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 (integer or None (default)) – The seed for the random number generator.

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)[source]#

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 or None (default)) – Seed for the random number generator.

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)[source]#

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 (integer or None (default)) – Seed for the random number generator.

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

Example

>>> import xgi
>>> H = xgi.fast_random_hypergraph(50, [0.1, 0.01])
random_hypergraph(n, ps, order=None, seed=None)[source]#

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 (integer, random_state, or None (default)) – Indicator of random number generation state.

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.

Example

>>> import xgi
>>> H = xgi.random_hypergraph(50, [0.1, 0.01])
watts_strogatz_hypergraph(n, d, k, l, p, seed=None)[source]#