easygraph.functions.hypergraph.null_model package

Submodules

easygraph.functions.hypergraph.null_model.hypergraph_classic module

easygraph.functions.hypergraph.null_model.hypergraph_classic.complete_hypergraph(n, include_singleton=False)[source]
easygraph.functions.hypergraph.null_model.hypergraph_classic.empty_hypergraph(N=1)[source]
Parameters

  • Hypergraph (N number of node in) –

  • 1 (default) –

Return type

A eg.Hypergraph with n_num node, without any hyperedge.

easygraph.functions.hypergraph.null_model.lattice module

Generators for some lattice hypergraphs.

All the functions in this module return a Hypergraph class (i.e. a simple, undirected hypergraph).

easygraph.functions.hypergraph.null_model.lattice.ring_lattice(n, d, k, l)[source]

A ring lattice hypergraph.

A d-uniform hypergraph on n nodes where each node is part of k edges and the overlap between consecutive edges is d-l.

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

Returns

The generated hypergraph

Return type

Hypergraph

Raises

EasyGraphError – If k is negative.

Notes

ring_lattice(n, 2, k, 0) is a ring lattice graph where each node has k//2 edges on either side.

easygraph.functions.hypergraph.null_model.random module

easygraph.functions.hypergraph.null_model.random.chung_lu_hypergraph(k1, k2, seed=None)[source]

A function to generate a Chung-Lu hypergraph

Parameters

  • k1 (dict) – Dict where the keys are node ids and the values are node degrees.

  • k2 (dict) – dict 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 easygraph as eg
>>> 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 = eg.chung_lu_hypergraph(k1, k2)
easygraph.functions.hypergraph.null_model.random.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 easygraph as eg; 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 = eg.dcsbm_hypergraph(k1, k2, g1, g2, omega)
easygraph.functions.hypergraph.null_model.random.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) – List of probabilities (between 0 and 1) to create a hyperedge at each order d between any d+1 nodes. For example, ps[0] is the wiring probability of any edge (2 nodes), ps[1] of any triangles (3 nodes).

  • order (int of None (default)) – If None, ignore. If int, generates a uniform hypergraph with edges of order order (ps must have only one element).

  • seed (integer or None (default)) – Seed for the random number generator.

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

Example

>>> import easygraph as eg
>>> H = eg.random_hypergraph(50, [0.1, 0.01])
easygraph.functions.hypergraph.null_model.random.uniform_hypergraph_Gnp(k: int, num_v: int, prob: float, n_workers=None)[source]

Return a random k-uniform hypergraph with num_v vertices and probability prob of choosing a hyperedge.

Parameters

  • num_v (int) – The Number of vertices.

  • k (int) – The Number of vertices in each hyperedge.

  • prob (float) – Probability of choosing a hyperedge.

Examples

>>> import easygraph as eg
>>> hg = eg.random.uniform_hypergraph_Gnp(3, 5, 0.5)
>>> hg.e
([(0, 1, 3), (0, 1, 4), (0, 2, 4), (1, 3, 4), (2, 3, 4)], [1.0, 1.0, 1.0, 1.0, 1.0])
easygraph.functions.hypergraph.null_model.random.watts_strogatz_hypergraph(n, d, k, l, p, seed=None)[source]
Parameters

  • n (int) –

  • nodes (The number of) –

  • 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 probability of rewiring each edge

  • seed –

easygraph.functions.hypergraph.null_model.simple module

easygraph.functions.hypergraph.null_model.simple.star_clique(n_star, n_clique, d_max)[source]

Generate a star-clique structure

That is a star network and a clique network, connected by one pairwise edge connecting the centre of the star to the clique. network, the each clique is promoted to a hyperedge up to order d_max.

Parameters

  • n_star (int) – Number of legs of the star

  • n_clique (int) – Number of nodes in the clique

  • d_max (int) – Maximum order up to which to promote cliques to hyperedges

Returns

H

Return type

Hypergraph

Examples

>>> import easygraph as eg
>>> H = eg.star_clique(6, 7, 2)

Notes

The total number of nodes is n_star + n_clique.

easygraph.functions.hypergraph.null_model.uniform module

Generate random uniform hypergraphs.

easygraph.functions.hypergraph.null_model.uniform.uniform_HPPM(n, m, rho, k, epsilon, seed=None)[source]

Construct the m-uniform hypergraph planted partition model (m-HPPM)

Parameters

  • n (int > 0) – Number of nodes

  • m (int > 0) – Hyperedge size

  • rho (float between 0 and 1) – The fraction of nodes in community 1

  • k (float > 0) – Mean degree

  • epsilon (float > 0) – Imbalance parameter

  • seed (integer or None (default)) – The seed for the random number generator

Returns

The constructed m-HPPM hypergraph.

Return type

Hypergraph

Raises

EasyGraphError –

  • If rho is not between 0 and 1 - If the mean degree is negative. - If epsilon is not between 0 and 1

See also

uniform_HSBM

References

Nicholas W. Landry and Juan G. Restrepo. “Polarization in hypergraphs with community structure.” Preprint, 2023. https://doi.org/10.48550/arXiv.2302.13967

easygraph.functions.hypergraph.null_model.uniform.uniform_HSBM(n, m, p, sizes, seed=None)[source]

Create a uniform hypergraph stochastic block model (HSBM).

Parameters

  • n (int) – The number of nodes

  • m (int) – The hyperedge size

  • p (m-dimensional numpy array) – tensor of probabilities between communities

  • sizes (list or 1D numpy array) – The sizes of the community blocks in order

  • seed (integer or None (default)) – The seed for the random number generator

Returns

The constructed SBM hypergraph

Return type

Hypergraph

Raises

  • EasyGraphError –

    • If the length of sizes and p do not match. - If p is not a tensor with every dimension equal - If p is not m-dimensional - If the entries of p are not in the range [0, 1] - If the sum of the vector of sizes does not equal the number of nodes.

  • Exception – If there is an integer overflow error

See also

uniform_HPPM

References

Nicholas W. Landry and Juan G. Restrepo. “Polarization in hypergraphs with community structure.” Preprint, 2023. https://doi.org/10.48550/arXiv.2302.13967

easygraph.functions.hypergraph.null_model.uniform.uniform_erdos_renyi_hypergraph(n, m, p, p_type='degree', seed=None)[source]

Generate an m-uniform Erdős–Rényi hypergraph

This creates a hypergraph with n nodes where hyperedges of size m are created at random to obtain a mean degree of k.

Parameters

  • n (int > 0) – Number of nodes

  • m (int > 0) – Hyperedge size

  • p (float or int > 0) – Mean expected degree if p_type=”degree” and probability of an m-hyperedge if p_type=”prob”

  • p_type (str) – “degree” or “prob”, by default “degree”

  • seed (integer or None (default)) – The seed for the random number generator

Returns

The Erdos Renyi hypergraph

Return type

Hypergraph

See also

random_hypergraph

easygraph.functions.hypergraph.null_model.uniform.uniform_hypergraph_Gnm(k: int, num_v: int, num_e: int, n_workers=None)[source]

Return a random k-uniform hypergraph with num_v vertices and num_e hyperedges.

Parameters

  • k (int) – The Number of vertices in each hyperedge.

  • num_v (int) – The Number of vertices.

  • num_e (int) – The Number of hyperedges.

Examples

>>> import easygraph as eg
>>> hg = eg.uniform_hypergraph_Gnm(3, 5, 4)
>>> hg.e
([(0, 1, 2), (0, 1, 3), (0, 3, 4), (2, 3, 4)], [1.0, 1.0, 1.0, 1.0])
easygraph.functions.hypergraph.null_model.uniform.uniform_hypergraph_configuration_model(k, m, seed=None)[source]

A function to generate an m-uniform configuration model

Parameters

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

  • m (int) – specifies the hyperedge size

  • 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 degrees are not divisible by m, the algorithm still runs, but raises a warning and adds an additional connection to random nodes to satisfy this condition.

Notes

This algorithm normally creates multi-edges and loopy hyperedges. We remove the loopy hyperedges.

References

“The effect of heterogeneity on hypergraph contagion models” by Nicholas W. Landry and Juan G. Restrepo https://doi.org/10.1063/5.0020034

Example

>>> import easygraph as eg
>>> import random
>>> n = 1000
>>> m = 3
>>> k = {1: 1, 2: 2, 3: 3, 4: 3}
>>> H = eg.uniform_hypergraph_configuration_model(k, m)

Module contents