🧩 Core

Submodules

hypergraphx.core.undirected module

class hypergraphx.core.undirected.Hypergraph(edge_list=None, weighted=True, weights=None, hypergraph_metadata=None, node_metadata=None, edge_metadata=None, duplicate_policy=None, metadata_policy=None)

Bases: BaseHypergraph

A Hypergraph is a generalization of a graph where an edge (hyperedge) can connect any number of nodes. It is represented as a set of nodes and a set of hyperedges, where each hyperedge is a subset of nodes.

add_edge(edge, weight=None, metadata=None)

Add a hyperedge to the hypergraph. If the hyperedge is already in the hypergraph, its weight is updated.

Parameters:

• edge (tuple) – The hyperedge to add.

• weight (float, optional) – The weight of the hyperedge. If the hypergraph is weighted, this must be provided.

• metadata (dict, optional) – The metadata of the hyperedge.

Return type:

None

Raises:

ValueError – If the hypergraph is weighted and no weight is provided or if the hypergraph is not weighted and a weight is provided.

Notes

No multi-edges: duplicates never create a new edge. Control behavior via the hypergraph-level policies: - set_duplicate_policy(…) - set_metadata_policy(…)

Incidence metadata is not modified by duplicate adds; use incidence-metadata APIs explicitly.

add_edges(edge_list, weights=None, metadata=None)

Add a list of hyperedges to the hypergraph. If a hyperedge is already in the hypergraph, its weight is updated.

Parameters:

• edge_list (list) – The list of hyperedges to add.

• weights (list, optional) – The list of weights of the hyperedges. If the hypergraph is weighted, this must be provided.

• metadata (list, optional) – The list of metadata of the hyperedges.

Return type:

None

Raises:

ValueError – If the hypergraph is weighted and no weights are provided or if the hypergraph is not weighted and weights are provided.

Notes

No multi-edges: duplicates never create a new edge. See add_edge() for policies.

add_empty_edge(name, metadata)

adjacency_factor(t=0)

adjacency_matrix(return_mapping=False)

binary_incidence_matrix(return_mapping=False)

check_edge(edge)

Checks if the specified edge is in the hypergraph.

Parameters:

edge (tuple) – The edge to check.

Returns:

True if the edge is in the hypergraph, False otherwise.

Return type:

bool

clear()

connected_components(size=None, order=None)

degree(node, order=None, size=None)

degree_distribution(order=None, size=None)

degree_sequence(order=None, size=None)

dual_random_walk_adjacency(return_mapping=False)

get_adj_dict()

get_edge_list()

get_edge_metadata(edge)

get_edges(order=None, size=None, up_to=False, subhypergraph=False, keep_isolated_nodes=False, metadata=False)

get_incidence_metadata(edge, node)

get_weight(edge)

incidence_matrix(return_mapping=False)

is_connected(size=None, order=None)

is_isolated(node, size=None, order=None)

isolated_nodes(size=None, order=None)

largest_component(size=None, order=None)

largest_component_size(size=None, order=None)

node_connected_component(node, size=None, order=None)

num_connected_components(size=None, order=None)

populate_from_dict(data)

Populate the attributes of the hypergraph from a dictionary.

Parameters:

data (dict) – A dictionary containing the attributes to populate the hypergraph.

remove_edge(edge)

Remove an edge from the hypergraph.

Parameters:

edge (tuple) – The edge to remove.

Return type:

None

Raises:

KeyError – If the edge is not in the hypergraph.

remove_edges(edge_list)

Remove a list of edges from the hypergraph.

Parameters:

edge_list (list) – The list of edges to remove.

Return type:

None

Raises:

KeyError –

remove_node(node, keep_edges=False)

Remove a node from the hypergraph.

Parameters:

• node – The node to remove.

• keep_edges (bool, optional) – If True, the edges incident to the node are kept, but the node is removed from the edges. If False, the edges incident to the node are removed. Default is False.

Return type:

None

Raises:

ValueError – If the node is not in the hypergraph.

set_adj_dict(adj)

set_edge_list(edge_list)

set_edge_metadata(edge, metadata)

set_incidence_metadata(edge, node, metadata)

set_weight(edge, weight)

subhypergraph(nodes)

Return a subhypergraph induced by the nodes in the list.

Parameters:

nodes (list) – List of nodes to be included in the subhypergraph.

Returns:

Subhypergraph induced by the nodes in the list.

Return type:

Hypergraph

subhypergraph_by_orders(orders=None, sizes=None, keep_nodes=True)

Return a subhypergraph induced by the edges of the specified orders.

Parameters:

• orders (list, optional) – List of orders of the edges to be included in the subhypergraph. If None, the sizes parameter should be specified.

• sizes (list, optional) – List of sizes of the edges to be included in the subhypergraph. If None, the orders parameter should be specified.

• keep_nodes (bool, optional) – If True, the nodes of the original hypergraph are kept in the subhypergraph. If False, only the edges are kept. Default is True.

Returns:

Subhypergraph induced by the edges of the specified orders.

Return type:

Hypergraph

Raises:

ValueError – If both orders and sizes are None or if both orders and sizes are specified.

subhypergraph_largest_component(size=None, order=None)

Returns a subhypergraph induced by the nodes in the largest component of the hypergraph.

Parameters:

• size (int, optional) – The size of the hyperedges to consider

• order (int, optional) – The order of the hyperedges to consider

Returns:

Subhypergraph induced by the nodes in the largest component of the hypergraph.

Return type:

Hypergraph

to_line_graph(distance='intersection', s=1, weighted=False)

hypergraphx.core.base module

class hypergraphx.core.base.BaseHypergraph

Bases: SerializationMixin

Shared implementation for hypergraph-like data structures.

Subclasses are responsible for: - initializing adjacency maps before calling _init_base - defining edge normalization and node extraction hooks - overriding incidence handling where needed (e.g., directed edges)

Hook contract: - _normalize_edge(edge, **kwargs) -> edge_key - _edge_nodes(edge_key) -> iterable of nodes - _edge_size(edge_key) -> int (uses _edge_nodes by default) - _edge_key_without_node(edge_key, node) -> edge_key with node removed - _add_edge(edge_key, weight, metadata) for custom incidence behavior - _new_like() -> new instance of the same class - _hash_edge_nodes(edge_key) -> node representation for hashing/serialization

Duplicate edges / multi-edges: - Core hypergraphs do not support multi-edges: adding the same edge key twice never creates a new edge. - Duplicate handling is controlled via duplicate_policy and metadata_policy (per instance defaults, overridable per call). - If you need multiple distinct “instances” of the same interaction, model them explicitly:

use a TemporalHypergraph (different time) or MultiplexHypergraph (different layer).

add_node(node, metadata=None)

Add a node to the hypergraph if it does not already exist.

add_nodes(node_list, metadata=None)

Add multiple nodes to the hypergraph.

check_node(node)

Return True if the node exists in the hypergraph.

clear()

copy()

distribution_sizes()

property edges

edges_by_order(index_by='edge_key')

Return a dictionary mapping edge order to edges of that order.

Parameters:

index_by ({"edge_key", "edge_id", "position"}) – Representation for edges in the output.

edges_by_size(index_by='edge_key')

Return a dictionary mapping edge size to edges of that size.

Parameters:

index_by ({"edge_key", "edge_id", "position"}) – Representation for edges in the output.

get_all_edges_metadata()

get_all_incidences_metadata()

get_all_nodes_metadata()

get_duplicate_policy()

get_edge_metadata(edge_key)

get_hypergraph_metadata()

get_incidence_metadata(edge_key, node)

get_incident_edges(node, order=None, size=None)

Return edges incident to a node, optionally filtered by order or size.

get_metadata_policy()

get_neighbors(node, order=None, size=None)

Return the set of neighbors of a node via incident edges.

get_node_metadata(node)

get_nodes(metadata=False)

Return nodes, optionally with their metadata.

get_orders()

Return the order of each edge.

get_sizes()

Return the size (cardinality) of each edge.

get_weight(edge_key)

get_weights(order=None, size=None, up_to=False, asdict=False)

Return edge weights, optionally filtered by order or size.

incidence_dict(axis='node', *, index_by='edge_key', node_order=None)

Return a dictionary representation of incidences.

Parameters:

• axis ({"node", "edge"}) – If “node”, map nodes to incident edges. If “edge”, map edges to their nodes.

• index_by ({"edge_key", "edge_id", "position"}) – Representation for edges when axis=”node”.

• node_order (list, optional) – If provided, return node indices based on this ordering.

incident_edges_by_node(index_by='edge_key', node_order=None)

Return incident edges for each node.

Parameters:

• index_by ({"edge_key", "edge_id", "position"}) – Representation for incident edges.

• node_order (list, optional) – If provided, return a list aligned to this order.

is_uniform()

Return True if all edges have the same size.

is_weighted()

isolates(node_order=None)

Return isolated nodes.

Parameters:

node_order (list, optional) – If provided, return indices into this order instead of node labels.

iter_edges()

Iterate over edge keys (user-facing).

iter_nodes()

Iterate over node labels (user-facing).

max_order()

max_size()

property nodes

non_isolates(node_order=None)

Return non-isolated nodes.

Parameters:

node_order (list, optional) – If provided, return indices into this order instead of node labels.

num_edges(order=None, size=None, up_to=False)

Return the number of edges, optionally filtered by order or size.

num_nodes()

remove_attr_from_edge_metadata(edge_key, field)

remove_attr_from_node_metadata(node, field)

remove_node(node, keep_edges=False)

Remove a node, optionally preserving incident edges without it.

remove_nodes(node_list, keep_edges=False)

Remove multiple nodes from the hypergraph.

set_attr_to_edge_metadata(edge_key, field, value)

set_attr_to_hypergraph_metadata(field, value)

set_attr_to_node_metadata(node, field, value)

set_duplicate_policy(policy)

set_edge_metadata(edge_key, metadata)

set_hypergraph_metadata(metadata)

set_incidence_metadata(edge_key, node, metadata)

set_metadata_policy(policy)

set_node_metadata(node, metadata)

set_weight(edge_key, weight)

summary(*, include_size_distribution=True, max_size_bins=20)

Lightweight summary for quick inspection.

Returns a small dict suitable for printing/logging.

validate_invariants()

Public hook to validate internal consistency (useful in debugging).

class hypergraphx.core.base.SerializationMixin

Bases: object

Serialization and hashing helpers for hypergraph-like classes.

expose_attributes_for_hashing()

expose_data_structures()

get_mapping()

populate_from_dict(data)

hypergraphx.core.directed module

class hypergraphx.core.directed.DirectedHypergraph(edge_list=None, weighted=True, weights=None, hypergraph_metadata=None, node_metadata=None, edge_metadata=None, duplicate_policy=None, metadata_policy=None)

Bases: BaseHypergraph

A Directed Hypergraph is a generalization of a graph in which hyperedges have a direction. Each hyperedge connects a set of source nodes to a set of target nodes.

add_edge(edge, weight=None, metadata=None)

Add a directed hyperedge to the hypergraph. If the hyperedge already exists, its weight is updated.

Parameters:

• edge (tuple of tuples) – The directed hyperedge to add, represented as (source_nodes, target_nodes).

• weight (float, optional) – The weight of the hyperedge. If the hypergraph is weighted, this must be provided.

• metadata (dict, optional) – The metadata of the hyperedge.

Return type:

None

Raises:

ValueError – If the hypergraph is weighted and no weight is provided or if the hypergraph is not weighted and a weight is provided.

Notes

No multi-edges: duplicates never create a new edge. Control behavior via the hypergraph-level policies: - set_duplicate_policy(…) - set_metadata_policy(…)

Incidence metadata is not modified by duplicate adds; use incidence-metadata APIs explicitly.

add_edges(edge_list, weights=None, metadata=None)

Add a list of directed hyperedges to the hypergraph. If a hyperedge is already in the hypergraph, its weight is updated.

Parameters:

• edge_list (list of tuples of tuples) – The list of directed hyperedges to add (each as (source_nodes, target_nodes)).

• weights (list, optional) – The list of weights of the hyperedges.

• metadata (list, optional) – The list of metadata of the hyperedges.

Return type:

None

Notes

No multi-edges: duplicates never create a new edge. See add_edge() for policies.

add_node(node, metadata=None)

Add a node to the hypergraph. If the node is already in the hypergraph, nothing happens.

Parameters:

node (object) – The node to add.

Return type:

None

add_nodes(node_list, metadata=None)

Add a list of nodes to the hypergraph.

Parameters:

• node_list (list) – The list of nodes to add.

• metadata (dict, optional) – Optional mapping of nodes to metadata.

Return type:

None

check_edge(edge)

Checks if the specified edge is in the hypergraph.

Parameters:

edge (tuple) – The edge to check.

Returns:

True if the edge is in the hypergraph, False otherwise.

Return type:

bool

check_node(node)

Checks if the specified node is in the hypergraph.

Parameters:

node (Object) – The node to check.

Returns:

True if the node is in the hypergraph, False otherwise.

Return type:

bool

clear()

degree(node, order=None, size=None)

degree_distribution(order=None, size=None)

degree_sequence(order=None, size=None)

get_adj_dict(source_target)

get_all_edges_metadata()

get_all_incidences_metadata()

get_all_nodes_metadata()

get_edge_list()

get_edge_metadata(edge)

get_edges(order=None, size=None, up_to=False, subhypergraph=False, keep_isolated_nodes=False, metadata=False)

get_incidence_metadata(edge, node)

get_incident_edges(node, order=None, size=None)

Get the incident edges of a node.

Parameters:

• node (object) – The node of interest.

• order (int, optional) – The order of the hyperedges to consider. If None, all hyperedges are considered.

• size (int, optional) – The size of the hyperedges to consider. If None, all hyperedges are considered.

Returns:

The list of incident edges.

Return type:

list

get_neighbors(node, order=None, size=None)

Get the neighbors of a node in the hypergraph.

Parameters:

• node (object) – The node of interest.

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

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

Returns:

The neighbors of the node.

Return type:

set

Raises:

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

get_nodes(metadata=False)

Returns the list of nodes in the hypergraph.

get_source_edges(node, order=None, size=None)

Get the source edges in which a node is in the source set.

Parameters:

• node

• order

• size

Returns:

The list of incident in-edges.

Return type:

list

get_sources()

Returns the list of sources of the hyperedges in the hypergraph.

Returns:

List of sources of the hyperedges in the hypergraph.

Return type:

list

get_target_edges(node, order=None, size=None)

Get the hyperedges in which a node is in the target set.

Parameters:

• node

• order

• size

Returns:

The list of incident out-edges.

Return type:

list

get_targets()

Returns the list of targets of the hyperedges in the hypergraph.

Returns:

List of targets of the hyperedges in the hypergraph.

Return type:

list

get_weight(edge)

Returns the weight of the specified directed edge.

get_weights(order=None, size=None, up_to=False, asdict=False)

Returns the list of weights of the edges in the hypergraph. If order is specified, it returns the list of weights of the edges of the specified order. If size is specified, it returns the list of weights of the edges of the specified size. If both order and size are specified, it raises a ValueError. If up_to is True, it returns the list of weights of the edges of order smaller or equal to the specified order.

Parameters:

• order (int, optional) – Order of the edges to get the weights of.

• size (int, optional) – Size of the edges to get the weights of.

• up_to (bool, optional) – If True, it returns the list of weights of the edges of order smaller or equal to the specified order. Default is False.

Returns:

List of weights of the edges in the hypergraph.

Return type:

list

Raises:

ValueError – If both order and size are specified.

in_degree(node, order=None, size=None)

Return the in-degree of a node, counting incident edges where the node is a target.

Parameters:

• node (object) – The node of interest.

• order (int, optional) – The order of the hyperedges to consider.

• size (int, optional) – The size of the hyperedges to consider.

in_degree_distribution(order=None, size=None)

Return a histogram of in-degrees as a dict {degree: count}.

in_degree_sequence(order=None, size=None)

Return the in-degree for every node as a dict.

is_isolated(node, size=None, order=None)

is_uniform()

Check if the hypergraph is uniform, i.e. all hyperedges have the same size.

Returns:

True if the hypergraph is uniform, False otherwise.

Return type:

bool

isolated_nodes(size=None, order=None)

out_degree(node, order=None, size=None)

Return the out-degree of a node, counting incident edges where the node is a source.

Parameters:

• node (object) – The node of interest.

• order (int, optional) – The order of the hyperedges to consider.

• size (int, optional) – The size of the hyperedges to consider.

out_degree_distribution(order=None, size=None)

Return a histogram of out-degrees as a dict {degree: count}.

out_degree_sequence(order=None, size=None)

Return the out-degree for every node as a dict.

populate_from_dict(data)

Populate the attributes of the directed hypergraph from a dictionary.

Parameters:

data (dict) – A dictionary containing the attributes to populate the hypergraph.

remove_attr_from_edge_metadata(edge, field)

remove_attr_from_node_metadata(node, field)

remove_edge(edge)

Remove a directed edge from the hypergraph.

Parameters:

edge (tuple of tuples) – The edge to remove (source_nodes, target_nodes).

Return type:

None

remove_edges(edge_list)

Remove a list of edges from the hypergraph.

Parameters:

edge_list (list) – The list of edges to remove.

Return type:

None

Raises:

KeyError –

remove_node(node, keep_edges=False)

Remove a node from the hypergraph, with an option to keep or remove edges incident to it.

remove_nodes(node_list, keep_edges=False)

Remove a list of nodes from the hypergraph.

Parameters:

• node_list (list) – The list of nodes to remove.

• keep_edges (bool, optional) – If True, the edges incident to the nodes are kept, but the nodes are removed from the edges. If False, the edges incident to the nodes are removed. Default is False.

Return type:

None

Raises:

KeyError – If any of the nodes is not in the hypergraph.

set_adj_dict(adj_dict, source_target)

set_attr_to_edge_metadata(edge, field, value)

set_attr_to_hypergraph_metadata(field, value)

set_attr_to_node_metadata(node, field, value)

set_edge_list(edge_list)

set_edge_metadata(edge, metadata)

set_incidence_metadata(edge, node, metadata)

set_weight(edge, weight)

Sets the weight of the specified directed edge.

to_hypergraph(keep_node_metadata=True, keep_edge_metadata=True, keep_hypergraph_metadata=True)

Convert to an undirected Hypergraph by merging sources and targets.

Duplicate hyperedges are merged by summing weights and merging metadata.

to_line_graph(distance='intersection', s=1, weighted=False)

hypergraphx.core.multiplex module

class hypergraphx.core.multiplex.MultiplexHypergraph(edge_list=None, edge_layer=None, weighted=True, weights=None, hypergraph_metadata=None, node_metadata=None, edge_metadata=None, duplicate_policy=None, metadata_policy=None)

Bases: BaseHypergraph

A Multiplex Hypergraph is a hypergraph where hyperedges are organized into multiple layers. Each layer share the same node-set and represents a specific context or relationship between nodes, and hyperedges can have weights and metadata specific to their layer.

add_edge(edge, layer=None, weight=None, metadata=None)

Add a hyperedge to the hypergraph. If the hyperedge is already in the hypergraph, its weight is updated.

Parameters:

• edge (tuple) – The hyperedge to add.

• layer (str, optional) – The layer to which the hyperedge belongs. If not provided, edge must be a packed (layer, edge) tuple.

• weight (float, optional) – The weight of the hyperedge. If the hypergraph is weighted, this must be provided.

• metadata (dict, optional) – The metadata of the hyperedge.

Return type:

None

Raises:

ValueError – If the hypergraph is weighted and no weight is provided or if the hypergraph is not weighted and a weight is provided.

Notes

No multi-edges: duplicates never create a new edge. Control behavior via: - duplicate_policy: ‘error’ | ‘ignore’ | ‘accumulate_weight’ | ‘replace_weight’ - metadata_policy: ‘replace’ | ‘merge’ | ‘ignore’

Incidence metadata is not modified by duplicate adds; use incidence-metadata APIs explicitly.

add_edges(edge_list, edge_layer=None, weights=None, metadata=None)

Add a list of hyperedges to the hypergraph. If a hyperedge is already in the hypergraph, its weight is updated.

Parameters:

• edge_list (list) – The list of hyperedges to add.

• edge_layer (list, optional) – The list of layers to which the hyperedges belong. If not provided, edge_list must contain packed (layer, edge) tuples.

• weights (list, optional) – The list of weights of the hyperedges. If the hypergraph is weighted, this must be provided.

• metadata (list, optional) – The list of metadata of the hyperedges.

Return type:

None

Raises:

ValueError – If the hypergraph is weighted and no weights are provided or if the hypergraph is not weighted and weights are provided.

add_node(node, metadata=None)

Add a node to the hypergraph. If the node is already in the hypergraph, nothing happens.

Parameters:

node (object) – The node to add.

Return type:

None

add_nodes(node_list, node_metadata=None)

Add a list of nodes to the hypergraph.

Parameters:

node_list (list) – The list of nodes to add.

Return type:

None

aggregated_hypergraph()

degree(node, order=None, size=None)

degree_sequence(order=None, size=None)

get_adj_dict()

get_dataset_metadata()

get_edge_list()

get_edge_metadata(edge, layer=None)

get_edges(*, layer=None, order=None, size=None, up_to=False, metadata=False)

Get multiplex edges (edge keys).

Parameters:

• layer (str, optional) – If provided, return only edges in this layer.

• order (int, optional) – Edge order filter (order = size - 1). Mutually exclusive with size.

• size (int, optional) – Edge size filter (cardinality). Mutually exclusive with order.

• up_to (bool, optional) – If True, include edges with order <= order (or size <= size).

• metadata (bool, optional) – If True, return a dict mapping edge key -> edge metadata.

Returns:

List of edge keys (layer, edge) or a dict {edge_key: metadata}.

Return type:

list | dict

get_existing_layers()

get_hypergraph_metadata()

get_incident_edges(node)

Return edges incident to a node, optionally filtered by order or size.

get_layer_metadata(layer_name)

get_nodes(metadata=False)

Return nodes, optionally with their metadata.

get_weight(edge, layer=None)

is_weighted()

populate_from_dict(data)

Populate the attributes of the multiplex hypergraph from a dictionary.

Parameters:

data (dict) – A dictionary containing the attributes to populate the hypergraph.

remove_attr_from_edge_metadata(edge, layer, field)

remove_attr_from_edge_metadata_key(edge_key, field)

remove_attr_from_node_metadata(node, field)

remove_edge(edge, layer=None)

Remove an edge from the multiplex hypergraph.

Parameters:

edge (tuple) – The edge to remove. Can be passed as: - edge=(nodes…) with layer=<str> - packed (layer, edge) tuple with layer=None

Raises:

ValueError – If the edge is not in the hypergraph.

remove_node(node, keep_edges=False)

Remove a node from the multiplex hypergraph.

Parameters:

• node (object) – The node to remove.

• keep_edges (bool, optional) – If True, edges incident to the node are kept but updated to exclude the node. If False, edges incident to the node are removed entirely. Default is False.

Raises:

ValueError – If the node is not in the hypergraph.

set_adj_dict(adj_dict)

set_attr_to_edge_metadata(edge, layer, field, value)

set_attr_to_edge_metadata_key(edge_key, field, value)

set_attr_to_hypergraph_metadata(field, value)

set_attr_to_node_metadata(node, field, value)

set_dataset_metadata(metadata)

set_edge_list(edge_list)

set_existing_layers(existing_layers)

set_hypergraph_metadata(metadata)

set_layer_metadata(layer_name, metadata)

set_weight(edge, layer=None, weight=None)

Set edge weight.

Accepts: - set_weight(edge, layer, weight) (explicit layer argument) - set_weight((layer, edge), weight=<…>) (packed edge key) - set_weight((layer, edge), <weight>) (packed edge key, positional weight) - set_weight((edge, layer), <weight>) (legacy packed edge key, positional weight)

summary(*, include_size_distribution=True, max_size_bins=20)

Lightweight summary for quick inspection.

Returns a small dict suitable for printing/logging.

to_hypergraph(keep_node_metadata=True, keep_edge_metadata=True, keep_hypergraph_metadata=True)

Convert to an undirected Hypergraph by dropping layer information.

Duplicate hyperedges are merged by summing weights and merging metadata.

hypergraphx.core.temporal module

class hypergraphx.core.temporal.TemporalHypergraph(edge_list=None, time_list=None, weighted=True, weights=None, hypergraph_metadata=None, node_metadata=None, edge_metadata=None, duplicate_policy=None, metadata_policy=None)

Bases: BaseHypergraph

A Temporal Hypergraph is a hypergraph where each hyperedge is associated with a specific timestamp. Temporal hypergraphs are useful for modeling systems where interactions between nodes change over time, such as social networks, communication networks, and transportation systems.

add_edge(edge, time=None, weight=None, metadata=None)

Add an edge to the temporal hypergraph. If the edge already exists, the weight is updated.

Parameters:

• edge (tuple) – The edge to add, or a packed temporal edge key (time, edge). If the hypergraph is undirected, edge should be a tuple of nodes. If the hypergraph is directed, edge should be a tuple of two tuples.

• time (int, optional) – The time at which the edge occurs. If not provided, edge must be a packed (time, edge) tuple (or (edge, time)).

• weight (float, optional) – The weight of the edge. Default is None.

• metadata (dict, optional) – Metadata for the edge. Default is an empty dictionary.

Raises:

• TypeError – If time is not an integer.

• ValueError – If the hypergraph is not weighted and weight is not None or 1.

Notes

Duplicate unweighted edges are ignored; duplicate weighted edges accumulate weights.

add_edges(edge_list, time_list=None, weights=None, metadata=None)

Add multiple edges to the temporal hypergraph.

Parameters:

• edge_list (iterable) – An iterable of edges to add. If time_list is not provided, it must contain packed (time, edge) tuples.

• time_list (iterable, optional) – An iterable of times corresponding to each edge in edge_list.

• weights (list, optional) – A list of weights for each edge in edge_list. Must be provided if the hypergraph is weighted.

• metadata (list, optional) – A list of metadata dictionaries for each edge in edge_list.

Raises:

• TypeError – If edge_list and time_list are not iterable.

• ValueError – If edge_list and time_list have mismatched lengths.

add_node(node, metadata=None)

Add a node to the hypergraph if it does not already exist.

add_nodes(node_list, metadata=None)

Add multiple nodes to the hypergraph.

adjacency_factor(t=0)

aggregate(time_window)

annealed_adjacency_matrix(return_mapping=False)

check_edge(edge, time=None)

Checks if the specified edge is in the hypergraph.

Parameters:

• edge (tuple) – The edge to check.

• time (int, optional) – The time to check. If not provided, edge must be a packed (time, edge) tuple.

Returns:

True if the edge is in the hypergraph, False otherwise.

Return type:

bool

check_node(node)

Checks if the specified node is in the hypergraph.

Parameters:

node (Object) – The node to check.

Returns:

True if the node is in the hypergraph, False otherwise.

Return type:

bool

clear()

degree(node, order=None, size=None)

degree_distribution(order=None, size=None)

degree_sequence(order=None, size=None)

get_adj_dict()

get_all_edges_metadata()

get_all_incidences_metadata()

get_all_nodes_metadata()

get_edge_list()

get_edge_metadata(edge, time=None)

get_edges(time_window=None, order=None, size=None, up_to=False, metadata=False)

Get the edges in the temporal hypergraph. If a time window is provided, only edges within the window are returned.

Parameters:

• time_window (tuple, optional) – A tuple of two integers representing the start and end times of the window.

• size (int, optional) – The size of the hyperedges to consider

• order (int, optional) – The order of the hyperedges to consider

• up_to (bool, optional)

• metadata (bool, optional) – If True, return edge metadata. Default is False.

Returns:

A list of edges in the hypergraph.

Return type:

list

get_hypergraph_metadata()

get_incidence_metadata(edge, time, node)

get_incident_edges(node, order=None, size=None)

Return edges incident to a node, optionally filtered by order or size.

get_neighbors(node, order=None, size=None)

Return the set of neighbors of a node via incident edges.

get_node_metadata(node)

get_nodes(metadata=False)

Return nodes, optionally with their metadata.

get_times()

Get the times of each edge in the hypergraph.

Returns:

A list of integers representing the times of each edge.

Return type:

list

get_times_for_edge(edge)

Get the times at which a specific set of nodes forms a hyperedge in the hypergraph.

Parameters:

edge (tuple) – The set of nodes forming the hyperedge.

Returns:

times – A list of times at which the hyperedge occurs.

Return type:

list

get_weight(edge, time=None)

is_isolated(node, size=None, order=None)

is_uniform()

Check if the hypergraph is uniform, i.e. all hyperedges have the same size.

Returns:

True if the hypergraph is uniform, False otherwise.

Return type:

bool

isolated_nodes(size=None, order=None)

max_time()

min_time()

populate_from_dict(data)

Populate the attributes of the temporal hypergraph from a dictionary.

Parameters:

data (dict) – A dictionary containing the attributes to populate the hypergraph.

remove_attr_from_edge_metadata(edge, time, field)

remove_attr_from_node_metadata(node, field)

remove_edge(edge, time=None)

Remove an edge from the temporal hypergraph.

Parameters:

• edge (tuple) – The edge to remove.

• time (int) – The time at which the edge occurs.

Raises:

ValueError – If the edge is not in the hypergraph.

remove_edges(edge_list)

Remove a list of edges from the hypergraph.

Parameters:

edge_list (list) – The list of edges to remove.

Return type:

None

Raises:

KeyError –

remove_node(node, keep_edges=False)

Remove a node from the temporal hypergraph.

Parameters:

• node (object) – The node to remove.

• keep_edges (bool, optional) – If True, edges incident to the node are kept but updated to exclude the node. If False, edges incident to the node are removed entirely. Default is False.

Raises:

ValueError – If the node is not in the hypergraph.

remove_nodes(node_list, keep_edges=False)

Remove a list of nodes from the hypergraph.

Parameters:

• node_list (list) – The list of nodes to remove.

• keep_edges (bool, optional) – If True, the edges incident to the nodes are kept, but the nodes are removed from the edges. If False, the edges incident to the nodes are removed. Default is False.

Return type:

None

Raises:

KeyError – If any of the nodes is not in the hypergraph.

set_adj_dict(adj_dict)

set_attr_to_edge_metadata(edge, time, field, value)

set_attr_to_hypergraph_metadata(field, value)

set_attr_to_node_metadata(node, field, value)

set_edge_list(edge_list)

set_edge_metadata(edge, time=None, metadata=None)

set_hypergraph_metadata(metadata)

set_incidence_metadata(edge, time, node, metadata)

set_node_metadata(node, metadata)

set_weight(edge, time=None, weight=None)

subhypergraph(time_window=None, add_all_nodes=False)

Create an hypergraph for each time of the Temporal Hypergraph.

Parameters:

• time_window (tuple[int,int]|None, optional) – Give the time window (a,b), only the times inside the interval [a,b) will be considered. If not specified all the times will be considered.

• add_all_nodes (bool, optional) – If True, the hypergraphs will have all the nodes of the Temporal Hypergraph even if they are not present in their corresponding time.

Returns:

dict – A dictionary where the keys are the time and the values are the hypergraphs

Return type:

dict[int, Hypergraph]

summary(*, include_size_distribution=True, max_size_bins=20)

Lightweight summary for quick inspection.

Returns a small dict suitable for printing/logging.

temporal_adjacency_matrix(return_mapping=False)

to_hypergraph(keep_node_metadata=True, keep_edge_metadata=True, keep_hypergraph_metadata=True)

Convert to an undirected Hypergraph by dropping time information.

Duplicate hyperedges are merged by summing weights and merging metadata.

Next steps

• 🚀 Quickstart

• 📏 Measures

• 🔗 Representations