📦 API Reference

Subpackages

Module contents

class hypergraphx.DirectedHypergraph(edge_list=None, weighted=True, weights=None, hypergraph_metadata=None, node_metadata=None, edge_metadata=None, duplicate_policy=None, metadata_policy=None)[source]

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

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

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

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

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

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

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()[source]
degree(node, order=None, size=None)[source]
degree_distribution(order=None, size=None)[source]
degree_sequence(order=None, size=None)[source]
get_adj_dict(source_target)[source]
get_all_edges_metadata()[source]
get_all_incidences_metadata()[source]
get_all_nodes_metadata()[source]
get_edge_list()[source]
get_edge_metadata(edge)[source]
get_edges(order=None, size=None, up_to=False, subhypergraph=False, keep_isolated_nodes=False, metadata=False)[source]
get_incidence_metadata(edge, node)[source]
get_incident_edges(node, order=None, size=None)[source]

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

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

Returns the list of nodes in the hypergraph.

get_source_edges(node, order=None, size=None)[source]

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

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

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

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

Returns the weight of the specified directed edge.

get_weights(order=None, size=None, up_to=False, asdict=False)[source]

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

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

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

in_degree_sequence(order=None, size=None)[source]

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

is_isolated(node, size=None, order=None)[source]
is_uniform()[source]

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)[source]
out_degree(node, order=None, size=None)[source]

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

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

out_degree_sequence(order=None, size=None)[source]

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

populate_from_dict(data)[source]

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)[source]
remove_attr_from_node_metadata(node, field)[source]
remove_edge(edge)[source]

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

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

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

remove_nodes(node_list, keep_edges=False)[source]

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)[source]
set_attr_to_edge_metadata(edge, field, value)[source]
set_attr_to_hypergraph_metadata(field, value)[source]
set_attr_to_node_metadata(node, field, value)[source]
set_edge_list(edge_list)[source]
set_edge_metadata(edge, metadata)[source]
set_incidence_metadata(edge, node, metadata)[source]
set_weight(edge, weight)[source]

Sets the weight of the specified directed edge.

to_hypergraph(keep_node_metadata=True, keep_edge_metadata=True, keep_hypergraph_metadata=True, mode='union', keep_direction_as=None)[source]

Convert to an undirected Hypergraph.

Duplicate hyperedges are merged by summing weights and merging metadata.

Parameters:

  • mode ({"union", "source", "target", "role_nodes"}, optional) – How each directed hyperedge is projected. "union" merges source and target nodes, "source" keeps only source nodes, "target" keeps only target nodes, and "role_nodes" keeps source and target incidences as distinct role-tagged nodes.

  • keep_direction_as (tuple[str, str] | bool | None, optional) – If provided and edge metadata is kept, store the original source and target tuples under these metadata keys. True uses ("source", "target").

to_line_graph(distance='intersection', s=1, weighted=False)[source]
class hypergraphx.Hypergraph(edge_list=None, weighted=True, weights=None, hypergraph_metadata=None, node_metadata=None, edge_metadata=None, duplicate_policy=None, metadata_policy=None)[source]

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

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

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)[source]
adjacency_factor(t=0)[source]
adjacency_matrix(return_mapping=False)[source]
binary_incidence_matrix(return_mapping=False)[source]
check_edge(edge)[source]

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()[source]
connected_components(size=None, order=None)[source]
degree(node, order=None, size=None)[source]
degree_distribution(order=None, size=None)[source]
degree_sequence(order=None, size=None)[source]
dual_random_walk_adjacency(return_mapping=False)[source]
get_adj_dict()[source]
get_edge_list()[source]
get_edge_metadata(edge)[source]
get_edges(order=None, size=None, up_to=False, subhypergraph=False, keep_isolated_nodes=False, metadata=False)[source]
get_incidence_metadata(edge, node)[source]
get_weight(edge)[source]
incidence_matrix(return_mapping=False)[source]
is_connected(size=None, order=None)[source]
is_isolated(node, size=None, order=None)[source]
isolated_nodes(size=None, order=None)[source]
largest_component(size=None, order=None)[source]
largest_component_size(size=None, order=None)[source]
node_connected_component(node, size=None, order=None)[source]
num_connected_components(size=None, order=None)[source]
populate_from_dict(data)[source]

Populate the attributes of the hypergraph from a dictionary.

Parameters:

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

remove_edge(edge)[source]

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

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

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)[source]
set_edge_list(edge_list)[source]
set_edge_metadata(edge, metadata)[source]
set_incidence_metadata(edge, node, metadata)[source]
set_weight(edge, weight)[source]
subhypergraph(nodes)[source]

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

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

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)[source]
exception hypergraphx.HypergraphxError[source]

Bases: Exception

Base exception for hypergraphx errors.

exception hypergraphx.InvalidFileTypeError[source]

Bases: ValueError, HypergraphxError

Raised when an unsupported file extension is provided.

exception hypergraphx.InvalidFormatError[source]

Bases: ValueError, HypergraphxError

Raised when an invalid format is provided.

exception hypergraphx.InvalidParameterError[source]

Bases: ValueError, HypergraphxError

Raised when invalid or conflicting parameters are provided.

exception hypergraphx.MissingEdgeError[source]

Bases: ValueError, HypergraphxError

Raised when an edge is missing from a hypergraph.

exception hypergraphx.MissingNodeError[source]

Bases: ValueError, HypergraphxError

Raised when a node is missing from a hypergraph.

class hypergraphx.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)[source]

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

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

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

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

Add a list of nodes to the hypergraph.

Parameters:

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

Return type:

None

aggregated_hypergraph()[source]
clear()[source]
degree(node, order=None, size=None)[source]
degree_sequence(order=None, size=None)[source]
get_adj_dict()[source]
get_dataset_metadata()[source]
get_edge_list()[source]
get_edge_metadata(edge, layer=None)[source]
get_edges(*, layer=None, order=None, size=None, up_to=False, metadata=False)[source]

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()[source]
get_hypergraph_metadata()[source]
get_incident_edges(node)[source]

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

get_layer_metadata(layer_name)[source]
get_nodes(metadata=False)[source]

Return nodes, optionally with their metadata.

get_weight(edge, layer=None)[source]
is_weighted()[source]
populate_from_dict(data)[source]

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)[source]
remove_attr_from_edge_metadata_key(edge_key, field)[source]
remove_attr_from_node_metadata(node, field)[source]
remove_edge(edge, layer=None)[source]

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

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)[source]
set_attr_to_edge_metadata(edge, layer, field, value)[source]
set_attr_to_edge_metadata_key(edge_key, field, value)[source]
set_attr_to_hypergraph_metadata(field, value)[source]
set_attr_to_node_metadata(node, field, value)[source]
set_dataset_metadata(metadata)[source]
set_edge_list(edge_list)[source]
set_existing_layers(existing_layers)[source]
set_hypergraph_metadata(metadata)[source]
set_layer_metadata(layer_name, metadata)[source]
set_weight(edge, layer=None, weight=None)[source]

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

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, layers=None, keep_layer_as=None)[source]

Convert to an undirected Hypergraph by dropping layer information.

Duplicate hyperedges are merged by summing weights and merging metadata.

Parameters:

  • layers (iterable | None, optional) – Layers to include. If not specified, all layers are converted.

  • keep_layer_as (str | None, optional) – If provided and edge metadata is kept, store the original layer under this metadata key before duplicate hyperedges are merged.

exception hypergraphx.ReadwriteError[source]

Bases: RuntimeError, HypergraphxError

Raised when read/write operations fail.

class hypergraphx.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)[source]

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

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

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

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

add_nodes(node_list, metadata=None)[source]

Add multiple nodes to the hypergraph.

adjacency_factor(t=0)[source]
aggregate(time_window)[source]
annealed_adjacency_matrix(return_mapping=False)[source]
check_edge(edge, time=None)[source]

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

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()[source]
degree(node, order=None, size=None)[source]
degree_distribution(order=None, size=None)[source]
degree_sequence(order=None, size=None)[source]
get_adj_dict()[source]
get_all_edges_metadata()[source]
get_all_incidences_metadata()[source]
get_all_nodes_metadata()[source]
get_edge_list()[source]
get_edge_metadata(edge, time=None)[source]
get_edges(time_window=None, order=None, size=None, up_to=False, metadata=False)[source]

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()[source]
get_incidence_metadata(edge, time, node)[source]
get_incident_edges(node, order=None, size=None)[source]

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

get_neighbors(node, order=None, size=None)[source]

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

get_node_metadata(node)[source]
get_nodes(metadata=False)[source]

Return nodes, optionally with their metadata.

get_times()[source]

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

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)[source]
is_isolated(node, size=None, order=None)[source]
is_uniform()[source]

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)[source]
max_time()[source]
min_time()[source]
populate_from_dict(data)[source]

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)[source]
remove_attr_from_node_metadata(node, field)[source]
remove_edge(edge, time=None)[source]

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, time_list=None)[source]

Remove a list of edges from the hypergraph.

Parameters:

  • edge_list (iterable) – The list of edges to remove. If time_list is not provided, this must contain packed (time, edge) tuples.

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

Return type:

None

Raises:

KeyError –

remove_node(node, keep_edges=False)[source]

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

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]
set_attr_to_edge_metadata(edge, time, field, value)[source]
set_attr_to_hypergraph_metadata(field, value)[source]
set_attr_to_node_metadata(node, field, value)[source]
set_edge_list(edge_list)[source]
set_edge_metadata(edge, time=None, metadata=None)[source]
set_hypergraph_metadata(metadata)[source]
set_incidence_metadata(edge, time, node, metadata)[source]
set_node_metadata(node, metadata)[source]
set_weight(edge, time=None, weight=None)[source]
subhypergraph(time_window=None, add_all_nodes=False)[source]

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

Lightweight summary for quick inspection.

Returns a small dict suitable for printing/logging.

temporal_adjacency_matrix(return_mapping=False)[source]
to_hypergraph(keep_node_metadata=True, keep_edge_metadata=True, keep_hypergraph_metadata=True, time_window=None, keep_time_as=None)[source]

Convert to an undirected Hypergraph by dropping time information.

Duplicate hyperedges are merged by summing weights and merging metadata.

Parameters:

  • time_window (tuple[int, int] | None, optional) – Convert only hyperedges with time in the half-open interval [time_window[0], time_window[1]). If not specified, all times are converted.

  • keep_time_as (str | None, optional) – If provided and edge metadata is kept, store the original time under this metadata key before duplicate hyperedges are merged.

hypergraphx.download_remote_dataset(dataset_name, *, fmt='hgx', timeout=30, verify_ssl=False, cache_dir=None, overwrite=False, catalog_url=None, use_catalog=True, dataset_info=None)[source]

Download and cache a remote dataset without loading it into memory.

Parameters:

  • dataset_name (str) – Dataset identifier, such as "zoo" or "contacts-hospital".

  • fmt ({"hgx", "binary", "json"} or None, default="hgx") – Remote format to download. If explicitly set to None, JSON URLs are tried first, then binary URLs.

  • timeout (int, default=30) – Download timeout in seconds.

  • verify_ssl (bool, default=False) – Whether to verify TLS certificates.

  • cache_dir (path-like, optional) – Cache directory. Defaults to ~/.cache/hypergraphx/datasets or the HYPERGRAPHX_DATA_CACHE environment variable.

  • overwrite (bool, default=False) – If True, re-download even when a matching cached file exists.

  • catalog_url (str, optional) – Catalog metadata URL used to resolve dataset download URLs.

  • use_catalog (bool, default=True) – If True, resolve download URLs from the remote catalog before falling back to legacy hard-coded URL patterns.

  • dataset_info (dict, optional) – Already loaded catalog entry. Passing this avoids reloading the catalog when downloading many datasets.

Returns:

Local decompressed cache path, suitable for load_hypergraph(...).

Return type:

pathlib.Path

hypergraphx.download_remote_datasets(dataset_names=None, *, attributes=None, match_all=True, fmt='hgx', timeout=30, verify_ssl=False, cache_dir=None, overwrite=False, catalog_url=None, continue_on_error=False, progress_callback=None)[source]

Download and cache multiple remote datasets.

Parameters:

  • dataset_names (str | Iterable[str], optional) – Dataset names, filenames, or directories to download explicitly.

  • attributes (str | Iterable[str], optional) – Tag/category names used to select datasets from the catalog. If both dataset_names and attributes are provided, named datasets are filtered by the requested attributes.

  • match_all (bool, default=True) – If True, selected datasets must contain all requested attributes. If False, any requested attribute is enough.

  • fmt ({"hgx", "binary", "json"} or None, default="hgx") – Remote format to download.

  • timeout (int, default=30) – Download timeout in seconds.

  • verify_ssl (bool, default=False) – Whether to verify TLS certificates.

  • cache_dir (path-like, optional) – Cache directory. Defaults to ~/.cache/hypergraphx/datasets or the HYPERGRAPHX_DATA_CACHE environment variable.

  • overwrite (bool, default=False) – If True, re-download even when matching cached files exist.

  • catalog_url (str, optional) – Catalog metadata URL used to resolve dataset download URLs.

  • continue_on_error (bool, default=False) – If True, keep downloading after a dataset fails and store the exception in that dataset’s result record. If False, raise on the first failure.

  • progress_callback (callable, optional) – Called after each dataset with its result record.

Returns:

Mapping from canonical dataset name to records with path, metadata, error, and status fields.

Return type:

dict

hypergraphx.get_remote_dataset_info(dataset_name, *, timeout=30, verify_ssl=False, catalog_url=None)[source]

Return the full catalog entry for a remote dataset.

dataset_name is matched against the catalog name, filename, and directory fields.

hypergraphx.iter_remote_hypergraphs(attributes=None, *, names=None, match_all=True, fmt='hgx', timeout=30, verify_ssl=False, catalog_url=None, include_metadata=False, store=True, cache_dir=None, overwrite=False)[source]

Yield remote hypergraphs selected by name or catalog tags/categories.

Parameters:

  • attributes (str | Iterable[str], optional) – Tag/category names to match, such as "Undirected" or ["Undirected", "Temporal"]. Matching is case-insensitive.

  • names (str | Iterable[str], optional) – Dataset names, filenames, or directories to load explicitly. If omitted, datasets are selected from attributes.

  • match_all (bool, default=True) – If True, a dataset must contain all requested attributes. If False, any requested attribute is enough.

  • fmt ({"hgx", "binary", "json"}, default="hgx") – Remote format to load for each matching dataset.

  • verify_ssl (bool, default=False) – Whether to verify TLS certificates for remote requests.

  • catalog_url (str, optional) – Catalog metadata URL used for filtering.

  • include_metadata (bool, default=False) – If True, yield (hypergraph, dataset_info) pairs. Otherwise yield only the hypergraph object.

  • store (bool, default=True) – Store downloaded datasets locally before loading them.

  • cache_dir (path-like, optional) – Cache directory. Defaults to ~/.cache/hypergraphx/datasets or the HYPERGRAPHX_DATA_CACHE environment variable.

  • overwrite (bool, default=False) – If True, re-download matching datasets even when cached files exist.

Notes

This is a generator: datasets are downloaded and loaded lazily as the iterator advances.

hypergraphx.list_remote_datasets(*, timeout=30, verify_ssl=False, catalog_url=None)[source]

List datasets advertised by the remote Hypergraphx-data catalog.

Returns a list of dictionaries with at least: - name - tags / categories - vertices - edges

Parameters:

  • timeout (int, default=30) – Download timeout in seconds.

  • verify_ssl (bool, default=False) – Whether to verify TLS certificates when downloading the catalog. Defaults to False for compatibility with the current dataset server.

  • catalog_url (str, optional) – Catalog metadata URL. Defaults to the Hypergraphx-data GitHub raw URL, or HYPERGRAPHX_DATA_CATALOG_URL if set.

Notes

catalog_url can point to the generated catalog.json file, a JSON list, or the legacy related-data.js file used by the website.

hypergraphx.load_hypergraph(file_name, *, fmt=None)[source]

Load a hypergraph from disk.

Parameters:

  • file_name (str or path-like) – Input file path.

  • fmt ({"json", "pickle", "hgr"} | None) – Optional override for the input format. If None (default), infer format from the file extension. Gzipped files with .gz suffix are supported for each local format, such as .json.gz and .hgx.gz.

hypergraphx.load_hypergraph_from_server(dataset_name, *, fmt='hgx', as_dict=False, timeout=30, verify_ssl=False, store=True, cache_dir=None, overwrite=False, catalog_url=None, use_catalog=True, dataset_info=None)[source]

Load a dataset by name from the remote Hypergraphx-data server.

Parameters:

  • dataset_name (str) – Dataset identifier, such as "zoo" or "contacts-hospital".

  • fmt ({"hgx", "binary", "json"} or None, default="hgx") – Remote format to load. "hgx" and "binary" load the compact binary Hypergraphx format; "json" loads the JSON format. If explicitly set to None, JSON URLs are tried first, then binary URLs.

  • as_dict (bool, default=False) – If True, return the exposed internal data-structure dictionary instead of a hypergraph object.

  • timeout (int, default=30) – Download timeout in seconds.

  • verify_ssl (bool, default=False) – Whether to verify TLS certificates. Defaults to False for compatibility with the current dataset server certificate chain.

  • store (bool, default=True) – Store the decompressed remote dataset locally before loading it. Cached files are reused on later calls.

  • cache_dir (path-like, optional) – Cache directory. Defaults to ~/.cache/hypergraphx/datasets or the HYPERGRAPHX_DATA_CACHE environment variable.

  • overwrite (bool, default=False) – If True, re-download even when a matching cached file exists.

  • catalog_url (str, optional) – Catalog metadata URL used to resolve dataset download URLs.

  • use_catalog (bool, default=True) – If True, resolve download URLs from the remote catalog before falling back to legacy hard-coded URL patterns.

  • dataset_info (dict, optional) – Already loaded catalog entry. Passing this avoids reloading the catalog when loading many datasets.

Returns:

Loaded hypergraph object, or its exposed dictionary if as_dict=True.

Return type:

Hypergraph | DirectedHypergraph | TemporalHypergraph | MultiplexHypergraph | dict

Notes

The loader tries current per-dataset .json.gz / .hgx.gz URLs first and keeps older flat URLs as fallbacks. When store=True, compressed downloads are decompressed before being written to the cache.

hypergraphx.save_hypergraph(hypergraph, file_name, *, fmt='json', binary=None)[source]

Save a hypergraph to disk.

Parameters:

  • hypergraph – Hypergraph-like object.

  • file_name (str) – Output file path.

  • fmt ({"json", "pickle"}) – Output format (default: “json”).

  • binary (bool | None) – Backward-compatible alias for fmt=”pickle” when True. If provided, overrides fmt and emits a DeprecationWarning.

hypergraphx.search_remote_datasets(query=None, *, tags=None, match_all_tags=True, source=None, license=None, min_nodes=None, max_nodes=None, min_edges=None, max_edges=None, timeout=30, verify_ssl=False, catalog_url=None)[source]

Search the remote Hypergraphx-data catalog.

Parameters:

  • query (str, optional) – Case-insensitive substring matched against dataset names and tags.

  • tags (str | Iterable[str], optional) – Tags/categories to require. Matching is case-insensitive.

  • match_all_tags (bool, default=True) – If True, all requested tags must be present. If False, any requested tag is enough.

  • source (str, optional) – Case-insensitive substring matched against the source URL/text.

  • license (str, optional) – Case-insensitive substring matched against the license identifier/text.

  • min_nodes (int, optional) – Inclusive size filters using catalog vertices and edges.

  • max_nodes (int, optional) – Inclusive size filters using catalog vertices and edges.

  • min_edges (int, optional) – Inclusive size filters using catalog vertices and edges.

  • max_edges (int, optional) – Inclusive size filters using catalog vertices and edges.

Returns:

Matching catalog entries in catalog order.

Return type:

list[dict]

See also

list_remote_datasets

Return the full remote catalog.

iter_remote_hypergraphs

Lazily load matching remote hypergraphs.