🎲 Generation

Submodules

hypergraphx.generation.activity_driven module

hypergraphx.generation.activity_driven.HOADmodel(N, activities_per_order, time=100, *, seed=None)[source]

Generate a temporal hypergraph according to the HOAD model.

Parameters:

  • N (int) – The number of nodes in the hypergraph.

  • activities_per_order (dict) – The dictionary of activities per order. The keys are the orders and the values are the activities.

  • time (int) – The number of time steps.

Returns:

HG – The temporal hypergraph generated according to the HOAD model.

Return type:

TemporalHypergraph

Examples

>>> import numpy as np
>>> from hypergraphx.generation import HOADmodel
>>> acts = {2: np.array([0.1, 0.2, 0.3])}  # order=2 => size=3 hyperedges
>>> T = HOADmodel(3, acts, time=5, seed=0)
>>> isinstance(T.get_edges(), list)
True
hypergraphx.generation.activity_driven.rnd_pwl(xmin, xmax, g, size=1, *, seed=None)[source]

hypergraphx.generation.configuration_model module

hypergraphx.generation.configuration_model.configuration_model(hypergraph, n_steps=1000, label='edge', order=None, size=None, n_clash=1, restrict_to_same_size=True, duplicate_output='merge', seed=None)[source]

Sample a randomized hypergraph using a configuration-model-style MCMC.

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:

Randomized hypergraph.

Return type:

Hypergraph

Raises:

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)
>>> isinstance(H2, Hypergraph)
True

>>> H3 = configuration_model(H, n_steps=10, seed=0, duplicate_output="count")
>>> H3.is_weighted()
True

hypergraphx.generation.hy_mmsbm_sampling module

MCMC sampler for the Hy-MMSBM probabilistic model, described in

“A framework to generate hypergraphs with community structure” Ruggeri N., Contisciani M., Battiston F., De Bacco C.

Notice that the sampler is separate from the probabilistic model itself. In this view, the sampler only takes care of any sampling-related operation, and refers back to the model to retrieve any probability-related value (e.g. Poisson probabilities, expected degree, etc.).

class hypergraphx.generation.hy_mmsbm_sampling.HyMMSBMSampler(u=None, w=None, max_hye_size=None, exact_dyadic_sampling=True, burn_in_steps=1000, intermediate_steps=1000, seed=42)[source]

Bases: object

Sampler for the Hy-MMSBM model. This class takes care of the approximate sampling routine described in

“A framework to generate hypergraphs with community structure” Ruggeri N., Contisciani M., Battiston F., De Bacco C.

sample(deg_seq=None, dim_seq=None, avg_deg=None, initial_hyg=None, allow_rescaling=False)[source]

Approximate hypergraph sampling routine presented in

“A framework to generate hypergraphs with community structure” Ruggeri N., Contisciani M., Battiston F., De Bacco C.

Possibly, condition the sampling on different quantities: the expected average degree, a given degree sequence and/or dimension sequence, or a hypergraph.

Parameters:

  • deg_seq (degree sequence) – This is specified as an array of degrees, one per node in the hypergraph.

  • dim_seq (dimension sequence) – This is specified as a dictionary with {key: value} pairs {dimension: number of hyperedges with that dimension}

  • avg_deg (average degree)

  • initial_hyg (an initial hypergraph to start the MCMC from.) – If initial_hyg is provided, all the other inputs (i.e. deg_seq, dim_seq, avg_deg, allow_rescaling) are ignored. The MCMC is started using initial_hyg as first configuration, which is statistically equivalent to conditioning on its degree and dimension sequences. During MCMC, the degree and dimension sequences in initial_hyg are preserved.

  • allow_rescaling (allow the rescaling of the u and w parameters in place.) – This adjusts for the sampling constraints, e.g. average degree.

Returns:

  • A generator of sampled hypergraphs.

  • Notice that all the generated hypergraphs are conditioned on the same degree and

  • dimension sequences (possibly provided as input, otherwise sampled at the

  • beginning and kept constant). To sample conditioning on different sequences, a

  • new call to this method is required.

hypergraphx.generation.hy_mmsbm_sampling.sample_truncated_poisson(lambd, rng=None)[source]

Sample a truncated Poisson. If X is a Poisson random variable with parameter lambda, the relative truncated Poisson variable Y with same parameter lambda is defined as Y = X | X > 0.

hypergraphx.generation.random module

Generate random hypergraphs

hypergraphx.generation.random.add_random_edge(hg, order=None, size=None, inplace=False, seed=None)[source]

Add a random hyperedge of a given order / size to a hypergraph.

Parameters:

  • hg (hypergraph) – The Hypergraph of interest.

  • order (int) – The order of the edge to add.

  • size (int) – The size of the edge to add.

  • inplace (bool) – Whether to modify the hypergraph in place or return a new one.

  • seed (int, optional) – Seed for the random number generator

Returns:

The hypergraph with the added edge or None if inplace is True.

Return type:

Hypergraph or None

Raises:

ValueError – If order and size are both specified or neither are specified.

Examples

>>> from hypergraphx import Hypergraph
>>> from hypergraphx.generation import add_random_edge
>>> H = Hypergraph(edge_list=[(0, 1), (1, 2)], weighted=False)
>>> H2 = add_random_edge(H, size=3, inplace=False, seed=0)
>>> H.num_edges(), H2.num_edges()
(2, 3)
hypergraphx.generation.random.add_random_edges(hg, num_edges, order=None, size=None, inplace=False, seed=None)[source]

Add random hyperedges of a given order / size to a hypergraph.

Parameters:

  • hg (hypergraph) – The Hypergraph of interest.

  • num_edges (int) – The number of edges to add.

  • order (int) – The order of the edges to add.

  • size (int) – The size of the edges to add.

  • inplace (bool) – Whether to modify the hypergraph in place or return a copy.

  • seed (int, optional) – Seed for the random number generator

Returns:

The hypergraph with the added edges or None if inplace is True.

Return type:

Hypergraph or None

Raises:

ValueError – If order and size are both specified or neither are specified.

hypergraphx.generation.random.random_hypergraph(num_nodes, num_edges_by_size, seed=None, dense_threshold=0.25, max_tries_factor=50)[source]

Generate a random hypergraph with unique hyperedges for each requested size.

The requested counts are interpreted as exact numbers of unique hyperedges. Sparse requests use rejection sampling. Dense requests sample combinations directly without replacement to avoid slowdown near saturation.

Parameters:

  • num_nodes (int)

  • num_edges_by_size (dict) – A dictionary mapping the size of the hyperedges to the number of hyperedges of that size.

  • seed (int, optional) – Seed for the random number generator.

  • dense_threshold (float, optional) – Fraction of all possible hyperedges above which combinations are sampled directly without replacement. Default is 0.25.

  • max_tries_factor (int, optional) – Rejection-sampling attempt budget, as a multiple of the requested edge count. If exceeded, direct combination sampling is used.

Returns:

A random hypergraph with the given number of nodes and hyperedges for each size.

Return type:

Hypergraph

Raises:

ValueError – If a requested size/count is invalid or asks for more unique hyperedges than exist.

Examples

>>> from hypergraphx.generation import random_hypergraph
>>> hg = random_hypergraph(10, {2: 5, 3: 3}, seed=0)
>>> hg.num_edges()
8
hypergraphx.generation.random.random_shuffle(hg, order=None, size=None, inplace=False, p=1.0, preserve_degree=False, seed=None)[source]

Shuffle the nodes of a hypergraph’s hyperedges of a given order/size, replacing a fraction p of them.

Parameters:

  • hg (Hypergraph) – The hypergraph to process.

  • p (float, optional) – The fraction of hyperedges to randomize (0 <= p <= 1). Default is 1.0.

  • order (int) – The order of the hyperedges to shuffle.

  • size (int) – The size of the hyperedges to shuffle.

  • inplace (bool, optional) – If True, modify the given hypergraph directly; if False, operate on a copy and return it.

  • preserve_degree (bool, optional) – If True, attempt to preserve the degree distribution of the nodes during shuffling.

  • seed (int, optional) – Seed for the random number generator.

Returns:

The shuffled hypergraph. If inplace=True, this is the input object.

Return type:

Hypergraph

Raises:

ValueError – If order and size are both specified or neither are specified, or if p is not between 0 and 1.

Examples

>>> from hypergraphx import Hypergraph
>>> from hypergraphx.generation import random_shuffle
>>> H = Hypergraph(edge_list=[(0, 1, 2), (2, 3, 4)], weighted=False)
>>> H2 = random_shuffle(H, size=3, p=1.0, inplace=False, seed=0)
>>> H is H2
False
hypergraphx.generation.random.random_shuffle_all_orders(hg, p=1.0, inplace=False, preserve_degree=False, seed=None)[source]

Shuffle the nodes of a hypergraph’s hyperedges of a given order/size, replacing a fraction p of them. The process is repeated for every order of interaction.

Parameters:

  • hg (Hypergraph) – The hypergraph to process.

  • p (float, optional) – The fraction of hyperedges to randomize (0 <= p <= 1). Default is 1.0.

  • inplace (bool, optional) – If True, modify the given hypergraph directly; if False, operate on a copy and return it.

  • preserve_degree (bool, optional) – If True, attempt to preserve the degree distribution of the nodes during shuffling.

  • seed (int, optional) – Seed for the random number generator.

Returns:

The hypergraph with shuffled hyperedges. This is either the original hypergraph (if inplace is True) or a new, modified copy (if inplace is False).

Return type:

Hypergraph

Raises:

ValueError – If p is not between 0 and 1.

Examples

>>> from hypergraphx import Hypergraph
>>> from hypergraphx.generation import random_shuffle_all_orders
>>> H = Hypergraph(edge_list=[(0, 1), (0, 1, 2)], weighted=False)
>>> H2 = random_shuffle_all_orders(H, p=1.0, inplace=False, seed=0)
>>> H.num_edges() == H2.num_edges()
True
hypergraphx.generation.random.random_uniform_hypergraph(num_nodes, size, num_edges, seed=None, dense_threshold=0.25, max_tries_factor=50)[source]

Generate a random hypergraph with a given number of unique same-size hyperedges.

Parameters:

  • num_nodes (int) – The number of nodes in the hypergraph.

  • size (int) – The size of the hyperedges.

  • num_edges (int) – The number of hyperedges of the given size.

  • seed (int, optional) – Seed for the random number generator.

  • dense_threshold (float, optional) – Fraction of all possible hyperedges above which combinations are sampled directly without replacement. Default is 0.25.

  • max_tries_factor (int, optional) – Rejection-sampling attempt budget, as a multiple of the requested edge count. If exceeded, direct combination sampling is used.

Returns:

A random hypergraph with the given number of nodes and hyperedges of the given size.

Return type:

Hypergraph

hypergraphx.generation.scale_free module

hypergraphx.generation.scale_free.scale_free_hypergraph(num_nodes, edges_by_size, alpha_by_size=1.0, rho=0, seed=None, enforce_unique_edges=True, max_tries_factor=50)[source]

Generate a hypergraph from a hidden-variable (fitness / activity) model with heavy-tailed node activities, and tunable inter-size rank correlation.

Parameters:

  • num_nodes (int) – Number of nodes (labeled 0..num_nodes-1).

  • edges_by_size (dict[int, int]) – Mapping {hyperedge size (cardinality): number of hyperedges}.

  • alpha_by_size (float | dict[int, float]) – Zipf exponent(s) controlling activity heterogeneity. Larger alpha => stronger hub dominance. If float, the same alpha is used for all sizes.

  • rho (float) – Equicorrelation of latent Gaussian scores across sizes (controls inter-size rank correlation of activities). Can be negative, subject to rho ∈ [-1/(m-1), 1] when m>1.

  • seed (int | None) – Seed for reproducibility.

  • enforce_unique_edges (bool) – If True, enforces a simple hypergraph per size (no duplicate hyperedges) by rejection sampling.

  • max_tries_factor (int) – Collision budget for uniqueness per size: ~ max_tries_factor * num_edges attempts.

Returns:

Generated hypergraph.

Return type:

Hypergraph

Module contents

Synthetic hypergraph generators.

This package exposes a curated set of generators at the package level for discoverability (e.g. hypergraphx.generation.random_hypergraph(…)).

Implementations are imported lazily on first use.

hypergraphx.generation.HOADmodel(*args, **kwargs)[source]
hypergraphx.generation.add_random_edge(*args, **kwargs)[source]
hypergraphx.generation.add_random_edges(*args, **kwargs)[source]
hypergraphx.generation.random_hypergraph(*args, **kwargs)[source]
hypergraphx.generation.random_shuffle(*args, **kwargs)[source]
hypergraphx.generation.random_shuffle_all_orders(*args, **kwargs)[source]
hypergraphx.generation.random_uniform_hypergraph(*args, **kwargs)[source]
hypergraphx.generation.scale_free_hypergraph(*args, **kwargs)[source]

Next steps