ash_model.ASH¶

class ash_model.ASH(backend='dense')[source]¶

Parameters:: backend (str) –

__init__(backend='dense')[source]¶

Initialize an ASH (Attributed Stream Hypergraph) instance.

Parameters:: backend (str) – The backend for storing temporal information on hyperedges. Supported values are “dense” (stores time → set[id]) and “interval” (stores id → list[(start, end)] disjoint intervals).
Raises:: ValueError – If an unsupported backend is specified.
Return type:: None

Examples

from ash_model.classes.undirected import ASH

# Dense (default) backend
H = ASH()

# Interval backend
H2 = ASH(backend="interval")

Methods

`__init__`([backend])	Initialize an ASH (Attributed Stream Hypergraph) instance.
`add_hyperedge`(nodes, start[, end])	Add a hyperedge to the ASH.
`add_hyperedges`(hyperedges, start[, end])	Add multiple hyperedges to the ASH.
`add_node`(node, start[, end, attr_dict])	Add a node to the ASH with optional attributes.
`add_nodes`(nodes, start[, end, node_attr_dict])	Add multiple nodes to the ASH with optional attributes.
`avg_number_of_hyperedges`()	Calculate the average number of hyperedges across all temporal snapshots.
`avg_number_of_nodes`()	Calculate the average number of nodes across all temporal snapshots.
`bipartite_projection`([start, end, keep_attrs])	Create a bipartite projection of the ASH.
`clique_projection`([start, end, keep_attrs])	Create a clique projection of the ASH.
`coverage`()	Calculate the coverage of the ASH, defined as the average number of nodes present across all temporal snapshots, normalized by the total number of nodes.
`degree`(node[, start, end, hyperedge_size])	Return the degree of a node, which is the number of hyperedges that contain the node
`degree_by_hyperedge_size`(node[, start, end])	Return the degree of a node by hyperedge size, which is a dictionary where keys are
`degree_distribution`([start, end])	Return the distribution of node degrees within the specified time window.
`dual_hypergraph`([start, end])	Create a dual hypergraph projection of the ASH.
`get_hyperedge_attribute`(hyperedge_id, ...)	Get a specific attribute of a hyperedge.
`get_hyperedge_attributes`([hyperedge_id])	Get all attributes of a hyperedge.
`get_hyperedge_id`(nodes)	Get the hyperedge ID for a given set of node IDs.
`get_hyperedge_nodes`(hyperedge_id)	Get the set of node IDs that form a hyperedge.
`get_hyperedge_weight`(hyperedge_id)	Get the weight of a hyperedge.
`get_node_attribute`(node, attr_name[, tid])	Get a specific attribute of a node at a given time.
`get_node_attributes`(node[, tid])	Get all attributes of a node at a given time.
`get_node_profile`(node[, tid])	Get the profile of a node.
`get_node_profiles_by_time`(node)	Get the profiles of a node at all available time instants.
`get_s_incident`(hyperedge_id, s[, start, end])	Get hyperedges that are incident to a given hyperedge with at least s nodes
`has_hyperedge`(edge[, start, end])	Check if a hyperedge is present in the ASH within the specified time window.
`has_node`(node[, start, end])	Check if a node is present in the ASH within the specified time window.
`hyperedge_contribution`(hyperedge_id)	Calculate the contribution of a hyperedge to the ASH, defined as the fraction of temporal snapshots in which the hyperedge is present.
`hyperedge_presence`(hyperedge_id[, as_intervals])	Get the presence of a hyperedge across all temporal snapshots.
`hyperedge_size_distribution`([start, end])	Return the distribution of hyperedge sizes within the specified time window.
`hyperedges`([start, end, hyperedge_size, as_ids])	Return a list of hyperedge IDs or their node sets present in the ASH within the specified time window.
`induced_hypergraph`(hyperedge_set[, keep_attrs])	Create an induced hypergraph from the ASH using a set of hyperedge IDs.
`list_hyperedge_attributes`([categorical])	List all attributes of hyperedges in the ASH.
`list_node_attributes`([categorical, tid])	List all attributes of nodes in the ASH, optionally filtered by time.
`neighbors`(node[, start, end, hyperedge_size])	Return the set of neighbors of a node, which are the nodes that share hyperedges with
`node_contribution`(node)	Calculate the contribution of a node to the ASH, defined as the fraction of temporal snapshots in which the node is present.
`node_presence`(node[, as_intervals])	Get the presence of a node across all temporal snapshots.
`nodes`([start, end])	Return a list of node IDs present in the ASH within the specified time window.
`number_of_hyperedges`([start, end])	Return the number of unique hyperedges present in the ASH within the specified time window.
`number_of_neighbors`(node[, start, end, ...])	Return the number of unique neighbors of a node, which are the nodes that share hyperedges
`number_of_nodes`([start, end])	Return the number of unique nodes present in the ASH within the specified time window.
`remove_hyperedge`(hyperedge_id[, start, end])	Remove a hyperedge from the ASH, including its presence in the specified time window.
`remove_hyperedges`(hyperedges[, start, end])	Remove multiple hyperedges from the ASH, including their presence in the specified time window.
`remove_node`(node[, start, end])	Remove a node from the ASH, including its attributes and all hyperedges it is part of, in the specified time window.
`remove_nodes`(nodes[, start, end])	Remove multiple nodes from the ASH, including their attributes and all hyperedges they are part of, in the specified time window.
`remove_unlabelled_nodes`(attr_name[, start, end])	Remove nodes that do not have a specific attribute in the specified time window.
`s_degree`(node, s[, start, end])	Compute the s-degree of a node, summing degrees for hyperedges of size at least s.
`s_line_graph`([s, start, end])	Create a line graph projection of the ASH, where each hyperedge is represented as a
`size`([start, end])	Return the number of hyperedges present in the ASH within the specified time window.
`star`(node[, start, end, hyperedge_size, as_ids])	Return the star of a node, which is the set of hyperedges that contain the node
`stream_interactions`()	Generate a stream of interactions in the ASH, yielding tuples of the form (time_id, hyperedge_id, event_type), where event_type is either "+" for activation or "-" for deactivation of a hyperedge at that time.
`temporal_slice`(start[, end, keep_attrs])	Create a temporal slice of the ASH from start to end (inclusive).
`temporal_snapshots_ids`()	Return a sorted list of all temporal snapshot ids (time instants) in the ASH.
`to_dict`()	Convert the ASH to a dictionary representation.
`uniformity`()	Calculate the uniformity of the ASH, defined as the fraction of pairs of nodes that are present together in at least one temporal snapshot, normalized by the total number of pairs.

__init__(backend='dense')[source]¶

Initialize an ASH (Attributed Stream Hypergraph) instance.

Parameters:: backend (str) – The backend for storing temporal information on hyperedges. Supported values are “dense” (stores time → set[id]) and “interval” (stores id → list[(start, end)] disjoint intervals).
Raises:: ValueError – If an unsupported backend is specified.
Return type:: None

Examples

from ash_model.classes.undirected import ASH

# Dense (default) backend
H = ASH()

# Interval backend
H2 = ASH(backend="interval")

temporal_snapshots_ids()[source]¶

Return a sorted list of all temporal snapshot ids (time instants) in the ASH. This method retrieves the keys from the internal snapshot store, which represent the time instants when hyperedges are present.

Returns:: Sorted list of temporal snapshot ids.
Return type:: List[int]

Examples

H = ASH()
H.add_node(1, 0)
H.add_node(2, 0)
H.add_hyperedge([1, 2], start=0)
tids = H.temporal_snapshots_ids()  # e.g., [0]

stream_interactions()[source]¶

Generate a stream of interactions in the ASH, yielding tuples of the form (time_id, hyperedge_id, event_type), where event_type is either “+” for activation or “-” for deactivation of a hyperedge at that time. This method iterates through the temporal snapshots and compares the sets of hyperedges present in consecutive snapshots to determine hyperedge changes.

Yield:: Tuples of (time_id, hyperedge_id, event_type).
Return type:: Generator[Tuple[int, str, str], None, None]

Examples

H = ASH()
H.add_node(1, 0, 1)
H.add_node(2, 0, 1)
H.add_hyperedge([1, 2], start=0, end=1)
events = list(H.stream_interactions())
# Example output: [(0, 'e1', '+'), (1, 'e1', '-')]

add_hyperedge(nodes, start, end=None, **kwargs)[source]¶

Add a hyperedge to the ASH. If nodes are not already present, they will be added. If end time is not specified, then the hyperedge is considered to be present only at start (end = start).

Parameters:

nodes (Iterable[int]) – Iterable of node IDs that form the hyperedge.
start (int) – Start time of the hyperedge.
end (int | None) – End time of the hyperedge (inclusive). If None, the hyperedge is considered to be present only at start.
kwargs (Any) – Optional attributes for the hyperedge.

Return type:

None

Examples

H = ASH()
H.add_node(1, 0)
H.add_node(2, 0)
H.add_hyperedge([1, 2], start=0, weight=3)
list(H.hyperedges())  # ['e1']
H.get_hyperedge_weight('e1')  # 3

add_hyperedges(hyperedges, start, end=None, **kwargs)[source]¶

Add multiple hyperedges to the ASH. If nodes are not already present, they will be added. All hyperedges will be added with the same start and end times. if end is not specified, then the hyperedges are considered to be present only at start (end = start).

Parameters:

hyperedges (Iterable[Iterable[int]]) – Iterable of iterables, where each inner iterable contains node IDs for a hyperedge.
start (int) – Start time of the hyperedges.
end (int | None) – End time of the hyperedges (inclusive). If None, the hyperedges are considered to be present only at start.
kwargs (Any) – Optional attributes for the hyperedges. These will be applied to all hyperedges.

Return type:

None

Examples

H = ASH()
H.add_nodes([1, 2, 3, 4], start=0)
H.add_hyperedges([[1, 2], [2, 3, 4]], start=0)
H.number_of_hyperedges()  # 2

add_node(node, start, end=None, attr_dict=None)[source]¶

Add a node to the ASH with optional attributes. Attributes can be provided as a dictionary of the form {attr_name: value} or as an NProfile instance. If the node is not already present, it will be created with the specified attributes. If end time is not specified, then the node is considered to be present only at start (end = start).

To add a node with different attributes at different times, you can call this method multiple times with different start and end values.

Parameters:

node (int) – Node ID to add.
start (int) – Start time of the node.
end (int | None) – End time of the node (inclusive). If None, the node is considered to be present only at start.
attr_dict (Dict[str, Any] | NProfile | None) – Optional attributes for the node. Can be a dictionary or an NProfile instance.

Return type:

None

Examples

H = ASH()
H.add_node(1, start=0, end=2, attr_dict={"group": "A"})
H.get_node_attribute(1, "group", tid=0)  # 'A'
H.has_node(1, 1)  # True

add_nodes(nodes, start, end=None, node_attr_dict=None)[source]¶

Add multiple nodes to the ASH with optional attributes. Attributes can be provided as a dictionary mapping node IDs to their attributes.

Parameters:

nodes (Iterable[int]) – Iterable of node IDs to add.
start (int) – Start time of the nodes.
end (int | None) – End time of the nodes (inclusive). If None, the nodes are considered to be present only at start.
node_attr_dict (Dict[int, NProfile | Dict[str, Any]] | None) – Optional dictionary mapping node IDs to their attributes. If None, no attributes are added.

Return type:

None

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0, node_attr_dict={1: {"color": "red"}})
H.number_of_nodes(0)  # 3
H.get_node_attribute(1, "color", 0)  # 'red'

remove_hyperedge(hyperedge_id, start=None, end=None)[source]¶

Remove a hyperedge from the ASH, including its presence in the specified time window.

Parameters:

hyperedge_id (str) – ID of the hyperedge to remove.
start (int | None) – Start time of the removal. If None, the hyperedge is removed from all times.
end (int | None) – End time of the removal (inclusive). If None, the hyperedge is removed only at start.

Return type:

None

Examples

H = ASH()
H.add_nodes([1, 2], start=0)
H.add_hyperedge([1, 2], start=0, end=2)
H.remove_hyperedge('e1', start=1, end=2)
H.has_hyperedge('e1', 0)  # True
H.has_hyperedge('e1', 1)  # False

remove_hyperedges(hyperedges, start=None, end=None)[source]¶

Remove multiple hyperedges from the ASH, including their presence in the specified time window.

Parameters:

hyperedges (Iterable[str]) – Iterable of hyperedge IDs to remove.
start (int | None) – Start time of the removal. If None, the hyperedges are removed from all times.
end (int | None) – End time of the removal (inclusive). If None, the hyperedges are removed only at start.

Return type:

None

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.add_hyperedges([[1, 2], [2, 3]], start=0)
ids = H.hyperedges()
H.remove_hyperedges(ids, start=0)
H.number_of_hyperedges(0)  # 0

remove_node(node, start=None, end=None)[source]¶

Remove a node from the ASH, including its attributes and all hyperedges it is part of, in the specified time window.

Parameters:

node (int) – Node ID to remove.
start (int | None) – Start time of the removal. If None, the node is removed from all times.
end (int | None) – End time of the removal (inclusive). If None, the node is removed only at start.

Return type:

None

Examples

H = ASH()
H.add_nodes([1, 2], start=0)
H.add_hyperedge([1, 2], start=0)
H.remove_node(1, start=0)
H.has_node(1, 0)  # False

remove_nodes(nodes, start=None, end=None)[source]¶

Remove multiple nodes from the ASH, including their attributes and all hyperedges they are part of, in the specified time window.

Parameters:

nodes (Iterable[int]) – Iterable of node IDs to remove.
start (int | None) – Start time of the removal. If None, the nodes are removed from all times.
end (int | None) – End time of the removal (inclusive). If None, the nodes are removed only at start.

Return type:

None

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.remove_nodes([1, 3], start=0)
set(H.nodes(0))  # {2}

remove_unlabelled_nodes(attr_name, start=None, end=None)[source]¶

Remove nodes that do not have a specific attribute in the specified time window. If no time window is specified, the nodes are checked in all times.

Parameters:

attr_name (str) – The name of the attribute to check for.
start (int | None) – Start time of the removal. If None, the nodes are checked in all times.
end (int | None) – End time of the removal (inclusive). If None, the nodes are checked only at start.

Return type:

None

Examples

H = ASH()
H.add_node(1, 0, attr_dict={"label": "A"})
H.add_node(2, 0)
H.remove_unlabelled_nodes("label", start=0)
set(H.nodes(0))  # {1}

nodes(start=None, end=None)[source]¶

Return a list of node IDs present in the ASH within the specified time window.

Parameters:

start (int | None) – Start time of the query. If None, all nodes are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

List of node IDs.

Return type:

List[int]

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.nodes(0)  # [1, 2, 3] (order not guaranteed)

hyperedges(start=None, end=None, hyperedge_size=None, as_ids=True)[source]¶

Return a list of hyperedge IDs or their node sets present in the ASH within the specified time window. Hyperedges are identified by their IDs (strings), or by sets of node IDs (frozensets). If hyperedge_size is specified, only hyperedges of that size are returned. The as_ids parameter determines whether to return hyperedge IDs or sets of node IDs.

Parameters:

start (Optional[int]) – Start time of the query. If None, all hyperedges are considered.
end (Optional[int]) – End time of the query (inclusive). If None, only the start time is considered.
hyperedge_size (Optional[int]) – If specified, only hyperedges of this size are returned.
as_ids (bool) – If True, return hyperedge IDs; if False, return sets of node IDs.

Returns:

List of hyperedge IDs or sets of node IDs.

Return type:

List[Union[str, frozenset[int]]]

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.add_hyperedges([[1, 2], [2, 3]], start=0)
H.hyperedges(0)           # e.g., ['e1', 'e2']
H.hyperedges(0, as_ids=False)  # [frozenset({1,2}), frozenset({2,3})]
H.hyperedges(0, hyperedge_size=2)  # only size-2 hyperedges

has_hyperedge(edge, start=None, end=None)[source]¶

Check if a hyperedge is present in the ASH within the specified time window. Accepts either a hyperedge ID (string) or an iterable of node IDs.

Parameters:

edge (str | Iterable[int]) – Hyperedge ID (string) or an iterable of node IDs.
start (int | None) – Start time of the query. If None, all hyperedges are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

True if the hyperedge is present, False otherwise.

Return type:

bool

Examples

H = ASH()
H.add_nodes([1, 2], start=0)
H.add_hyperedge([1, 2], start=0)
H.has_hyperedge('e1', 0)        # True
H.has_hyperedge([1, 2], 0)      # True
H.has_hyperedge([2, 3], 0)      # False

has_node(node, start=None, end=None)[source]¶

Check if a node is present in the ASH within the specified time window.

Parameters:

node (int) – Node ID to check.
start (int | None) – Start time of the query. If None, all nodes are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

True if the node is present, False otherwise.

Return type:

bool

Examples

H = ASH()
H.add_node(1, 0)
H.has_node(1, 0)  # True
H.has_node(2, 0)  # False

get_hyperedge_nodes(hyperedge_id)[source]¶

Get the set of node IDs that form a hyperedge. If the hyperedge does not exist, returns an empty frozenset.

Parameters:: hyperedge_id (str) – ID of the hyperedge.
Returns:: A frozenset of node IDs that are part of the hyperedge.
Return type:: frozenset[int]

Examples

H = ASH()
H.add_hyperedge([1, 2], start=0)
H.get_hyperedge_nodes('e1')  # frozenset({1, 2})

get_hyperedge_id(nodes)[source]¶

Get the hyperedge ID for a given set of node IDs. If the hyperedge does not exist, raises a KeyError.

Parameters:: nodes (Iterable[int]) – Iterable of node IDs that form the hyperedge.
Returns:: The ID of the hyperedge as a string.
Raises:: KeyError – If the hyperedge does not exist.
Return type:: str

Examples

H = ASH()
H.add_hyperedge([1, 2], start=0)
eid = H.get_hyperedge_id([1, 2])  # 'e1'

get_node_profiles_by_time(node)[source]¶

Get the profiles of a node at all available time instants.

Parameters:: node (int) – Node ID for which to get the profiles.
Returns:: A dictionary mapping time IDs to NProfile instances.
Return type:: Dict[int, NProfile]

Examples

from ash_model.classes.node_profile import NProfile

H = ASH()
H.add_node(1, 0, attr_dict=NProfile(1, role='A'))
H.add_node(1, 1, attr_dict=NProfile(1, role='B'))
profiles = H.get_node_profiles_by_time(1)
list(profiles.keys())  # [0, 1]

get_node_profile(node, tid=None)[source]¶

Get the profile of a node. The profile contains the node’s attributes at a specific time ID. If tid is None, the profile will be aggregated across all time IDs.

Parameters:

node (int) – Node ID for which to get the profile.
tid (int | None) – Time ID to filter the profile. If None, all time IDs are considered.

Returns:

An NProfile instance containing the node’s attributes.

Return type:

NProfile

Examples

from ash_model.classes.node_profile import NProfile

H = ASH()
H.add_node(1, 0, attr_dict=NProfile(1, team='X'))
p0 = H.get_node_profile(1, 0)
p_all = H.get_node_profile(1)  # aggregated profile

get_node_attribute(node, attr_name, tid=None)[source]¶

Get a specific attribute of a node at a given time. If tid is None, a dictionary mapping time IDs to attribute values is returned.

Parameters:

node (int) – Node ID for which to get the attribute.
attr_name (str) – Name of the attribute to retrieve.
tid (int | None) – Time ID to filter the attribute. If None, all time IDs are considered.

Returns:

The value of the attribute for the node at the specified time, or a dictionary of values if tid is None.

Return type:

Any | Dict[int, Any]

Examples

H = ASH()
H.add_node(1, start=0, attr_dict={"label": "A"})
H.get_node_attribute(1, "label", tid=0)  # 'A'
H.get_node_attribute(1, "label")  # {0: 'A'}

get_node_attributes(node, tid=None)[source]¶

Get all attributes of a node at a given time. If tid is None, returns attributes across all time IDs.

Parameters:

node (int) – Node ID for which to get the attributes.
tid (int | None) – Time ID to filter the attributes. If None, all time IDs are considered.

Returns:

A dictionary of attributes for the node at the specified time, or across all times if tid is None.

Return type:

Dict[str, Any]

Examples

H = ASH()
H.add_node(1, 0, attr_dict={"x": 10})
H.get_node_attributes(1, 0)  # {'x': 10}
H.get_node_attributes(1)     # {0: {'x': 10}}

list_node_attributes(categorical=False, tid=None)[source]¶

List all attributes of nodes in the ASH, optionally filtered by time. If tid is None, all attributes across all times are considered.

Parameters:

categorical (bool) – If True, only categorical attributes (strings) are returned.
tid (int | None) – Time ID to filter the attributes. If None, all time IDs are considered.

Returns:

A dictionary where keys are attribute names and values are sets of attribute values.

Return type:

Dict[str, Set[Any]]

Examples

H = ASH()
H.add_node(1, 0, attr_dict={"label": "A", "age": 30})
H.add_node(2, 0, attr_dict={"label": "B"})
all_attrs = H.list_node_attributes()
cat_attrs = H.list_node_attributes(categorical=True)

get_hyperedge_attribute(hyperedge_id, attribute_name)[source]¶

Get a specific attribute of a hyperedge.

Parameters:

hyperedge_id (str) – ID of the hyperedge.
attribute_name (str) – Name of the attribute to retrieve.

Returns:

The value of the attribute for the hyperedge, or None if not set

Return type:

Any

Examples

H = ASH()
H.add_hyperedge([1, 2], start=0, weight=5)
H.get_hyperedge_attribute('e1', 'weight')  # 5

get_hyperedge_attributes(hyperedge_id=None)[source]¶

Get all attributes of a hyperedge. If hyperedge_id is None, returns attributes for all hyperedges. If the hyperedge does not exist, returns an empty dictionary.

Parameters:: hyperedge_id (str | None) – ID of the hyperedge. If None, all hyperedges are considered.
Returns:: A dictionary of attributes for the hyperedge, or an empty dictionary if not found.
Return type:: Dict[str, Any]

Examples

H = ASH()
H.add_hyperedges([[1, 2], [2, 3]], start=0, weight=1)
attrs_all = H.get_hyperedge_attributes()
attrs_e1 = H.get_hyperedge_attributes('e1')

list_hyperedge_attributes(categorical=False)[source]¶

List all attributes of hyperedges in the ASH. If categorical is True, only categorical attributes (strings) are returned.

Parameters:: categorical (bool) – If True, only categorical attributes (strings) are returned.
Returns:: A dictionary where keys are attribute names and values are sets of attribute values.
Return type:: Dict[str, Set[Any]]

Examples

H = ASH()
H.add_hyperedge([1, 2], start=0, color='blue')
H.list_hyperedge_attributes()  # {'weight': {1}, 'color': {'blue'}}

get_hyperedge_weight(hyperedge_id)[source]¶

Get the weight of a hyperedge. If the weight is not set, returns 1 by default.

Parameters:: hyperedge_id (str) – ID of the hyperedge.
Returns:: The weight of the hyperedge, or 1 if not set.
Return type:: int | float

Examples

H = ASH()
H.add_hyperedge([1, 2], start=0)
H.get_hyperedge_weight('e1')  # 1

number_of_nodes(start=None, end=None)[source]¶

Return the number of unique nodes present in the ASH within the specified time window.

Parameters:

start (int | None) – Start time of the query. If None, all nodes are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

The number of unique nodes.

Return type:

int

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.number_of_nodes(0)  # 3

number_of_hyperedges(start=None, end=None)[source]¶

Return the number of unique hyperedges present in the ASH within the specified time window.

Parameters:

start (int | None) – Start time of the query. If None, all hyperedges are considered
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

The number of unique hyperedges.

Return type:

int

Examples

H = ASH()
H.add_hyperedges([[1, 2], [2, 3]], start=0)
H.number_of_hyperedges(0)  # 2

size(start=None, end=None)[source]¶

Return the number of hyperedges present in the ASH within the specified time window.

Parameters:

start (int | None) – Start time of the query. If None, all hyperedges are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

The number of hyperedges.

Return type:

int

Examples

H = ASH()
H.add_hyperedge([1, 2], start=0)
H.size(0)  # 1

hyperedge_size_distribution(start=None, end=None)[source]¶

Return the distribution of hyperedge sizes within the specified time window. The keys are the sizes of hyperedges (number of nodes in each hyperedge), and the values are the counts of hyperedges of that size.

Parameters:

start (int | None) – Start time of the query. If None, all hyperedges are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

A dictionary where keys are hyperedge sizes and values are counts of hyperedges of that size.

Return type:

Dict[int, int]

Examples

H = ASH()
H.add_hyperedges([[1, 2], [2, 3, 4]], start=0)
H.hyperedge_size_distribution(0)  # {2: 1, 3: 1}

degree_distribution(start=None, end=None)[source]¶

Return the distribution of node degrees within the specified time window. The keys are the degrees of nodes (number of hyperedges each node is part of), and the values are the counts of nodes with that degree.

Parameters:

start (int | None) – Start time of the query. If None, all nodes are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

A dictionary where keys are node degrees and values are counts of nodes with that degree.

Return type:

Dict[int, int]

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.add_hyperedges([[1, 2], [2, 3]], start=0)
H.degree_distribution(0)  # e.g., {1: 2, 2: 1}

star(node, start=None, end=None, hyperedge_size=None, as_ids=True)[source]¶

Return the star of a node, which is the set of hyperedges that contain the node within the specified time window. If hyperedge_size is specified, only hyperedges of that size are returned. The as_ids parameter determines whether to return hyperedge IDs (strings) or sets of node IDs (frozensets).

Parameters:

node (int) – Node ID for which to get the star.
start (Optional[int]) – Start time of the query. If None, all hyperedges are considered.
end (Optional[int]) – End time of the query (inclusive). If None, only the start time is considered.
hyperedge_size (Optional[int]) – If specified, only hyperedges of this size are returned.
as_ids (bool) – If True, return hyperedge IDs; if False, return sets of node IDs.

Returns:

A list of hyperedge IDs or sets of node IDs that form the star of the node within the specified time window.

Return type:

List[Union[str, frozenset[int]]]

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.add_hyperedges([[1, 2], [1, 3]], start=0)
H.star(1, 0)  # e.g., ['e1', 'e2']
H.star(1, 0, as_ids=False)  # [frozenset({1,2}), frozenset({1,3})]

degree(node, start=None, end=None, hyperedge_size=None)[source]¶

Return the degree of a node, which is the number of hyperedges that contain the node within the specified time window. If hyperedge_size is specified, only hyperedges of that size are counted.

Parameters:

node (int) – Node ID for which to get the degree.
start (int | None) – Start time of the query. If None, all hyperedges are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.
hyperedge_size (int | None) – If specified, only hyperedges of this size are counted.

Returns:

The degree of the node within the specified time window.

Return type:

int

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.add_hyperedges([[1, 2], [1, 3]], start=0)
H.degree(1, 0)  # 2

s_degree(node, s, start=None, end=None)[source]¶

Compute the s-degree of a node, summing degrees for hyperedges of size at least s.

Parameters:

node (int) – Node ID.
s (int) – Minimum hyperedge size to consider.
start (int | None) – Start time of the query. If None, all hyperedges are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

The s-degree value.

Return type:

int

Examples

H = ASH()
H.add_nodes([1, 2, 3, 4], start=0)
H.add_hyperedges([[1, 2], [1, 2, 3], [1, 3, 4]], start=0)
H.s_degree(1, s=3, start=0)  # counts only size >= 3 -> 2

degree_by_hyperedge_size(node, start=None, end=None)[source]¶

Return the degree of a node by hyperedge size, which is a dictionary where keys are hyperedge sizes (number of nodes in each hyperedge) and values are the counts of hyperedges of that size that contain the node within the specified time window.

Parameters:

node (int) – Node ID for which to get the degree by hyperedge size.
start (int | None) – Start time of the query. If None, all hyperedges are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

A dictionary where keys are hyperedge sizes and values are counts of hyperedges of that size that contain the node within the specified time window.

Return type:

Dict[int, int]

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.add_hyperedges([[1, 2], [1, 2, 3]], start=0)
H.degree_by_hyperedge_size(1, 0)  # {2: 1, 3: 1}

neighbors(node, start=None, end=None, hyperedge_size=None)[source]¶

Return the set of neighbors of a node, which are the nodes that share hyperedges with the specified node within the given time window. If hyperedge_size is specified, only hyperedges of that size are considered for determining neighbors.

Parameters:

node (int) – Node ID for which to get the neighbors.
start (int | None) – Start time of the query. If None, all hyperedges are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.
hyperedge_size (int | None) – If specified, only hyperedges of this size are considered for determining neighbors.

Returns:

A set of node IDs that are neighbors of the specified node within the specified time window.

Return type:

Set[int]

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.add_hyperedges([[1, 2], [1, 3]], start=0)
H.neighbors(1, 0)  # {2, 3}

number_of_neighbors(node, start=None, end=None, hyperedge_size=None)[source]¶

Return the number of unique neighbors of a node, which are the nodes that share hyperedges with the specified node within the given time window. If hyperedge_size is specified only hyperedges of that size are considered for determining neighbors.

Parameters:

node (int) – Node ID for which to get the number of neighbors.
start (int | None) – Start time of the query. If None, all hyperedges are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.
hyperedge_size (int | None) – If specified, only hyperedges of this size are considered for determining neighbors.

Returns:

The number of unique neighbors of the specified node within the specified time window.

Return type:

int

Examples

H = ASH()
H.add_nodes([1, 2, 3], start=0)
H.add_hyperedges([[1, 2], [1, 3]], start=0)
H.number_of_neighbors(1, 0)  # 2

bipartite_projection(start=None, end=None, keep_attrs=False)[source]¶

Create a bipartite projection of the ASH.

Parameters:

start (int | None) – Start time of the projection. If None, all hyperedges are considered.
end (int | None) – End time of the projection (inclusive). If None, only the start time is considered.
keep_attrs (bool) – If True, keep node and hyperedge attributes in the projection.

Returns:

A bipartite graph where nodes are hyperedges and nodes, and edges represent incidences between them.

Return type:

Graph

Examples

import networkx as nx
H = ASH()
H.add_hyperedge([1, 2], start=0)
G = H.bipartite_projection(0)
isinstance(G, nx.Graph)  # True

dual_hypergraph(start=None, end=None)[source]¶

Create a dual hypergraph projection of the ASH.

Parameters:

start (int | None) – Start time of the projection. If None, all hyperedges are considered.
end (int | None) – End time of the projection (inclusive). If None, only the start time is considered.

Returns:

A tuple containing the dual hypergraph and a mapping of original hyperedge IDs to new hyperedge IDs in the dual hypergraph.

Return type:

Tuple[ASH, Dict[str, str]]

Examples

H = ASH()
H.add_hyperedges([[1, 2], [2, 3]], start=0)
dual, mapping = H.dual_hypergraph(0)
isinstance(dual, ASH)  # True

clique_projection(start=None, end=None, keep_attrs=False)[source]¶

Create a clique projection of the ASH.

Parameters:

start (int | None) – Start time of the projection. If None, all hyperedges are considered.
end (int | None) – End time of the projection (inclusive). If None, only the start time is considered.
keep_attrs (bool) – If True, keep node and hyperedge attributes in the projection.

Returns:

A graph where each hyperedge is decomposed into a clique.

Return type:

Graph

Examples

import networkx as nx
H = ASH()
H.add_hyperedge([1, 2, 3], start=0)
G = H.clique_projection(0)
isinstance(G, nx.Graph)  # True

s_line_graph(s=1, start=None, end=None)[source]¶

Create a line graph projection of the ASH, where each hyperedge is represented as a node, and edges represent shared nodes between hyperedges.

Parameters:

s (int) – Minimum size of hyperedges to consider in the projection.
start (int | None) – Start time of the projection. If None, all hyperedges are considered.
end (int | None) – End time of the projection (inclusive). If None, only the start time is considered.

Returns:

A line graph where nodes represent hyperedges and edges represent shared nodes.

Return type:

Graph

Examples

import networkx as nx
H = ASH()
H.add_hyperedges([[1, 2], [2, 3]], start=0)
LG = H.s_line_graph(s=1, start=0)
isinstance(LG, nx.Graph)  # True

avg_number_of_nodes()[source]¶

Calculate the average number of nodes across all temporal snapshots.

Returns:: The average number of nodes.
Return type:: float

Examples

H = ASH()
H.add_node(1, 0)
H.add_node(2, 1)
avg = H.avg_number_of_nodes()  # e.g., 1.0

avg_number_of_hyperedges()[source]¶

Calculate the average number of hyperedges across all temporal snapshots.

Returns:: The average number of hyperedges.
Return type:: float

Examples

H = ASH()
H.add_hyperedge([1, 2], 0)
H.add_hyperedge([2, 3], 1)
H.avg_number_of_hyperedges()  # e.g., 1.0

node_presence(node, as_intervals=False)[source]¶

Get the presence of a node across all temporal snapshots. If as_intervals is True, returns the presence as intervals (start, end times). Otherwise, returns a list of time IDs where the node is present.

Parameters:

node (int) – Node ID for which to get the presence.
as_intervals (bool) – If True, return presence as intervals; if False, return presence as a list of time IDs.

Returns:

A list of time IDs or intervals where the node is present.

Return type:

List[int | Tuple[int, int]]

Examples

H = ASH()
H.add_node(1, start=0, end=2)
H.node_presence(1)           # [0, 1, 2]
H.node_presence(1, True)     # [(0, 2)]

hyperedge_presence(hyperedge_id, as_intervals=False)[source]¶

Get the presence of a hyperedge across all temporal snapshots. If as_intervals is True, returns the presence as intervals (start, end times). Otherwise, returns a list of time IDs where the hyperedge is present.

Parameters:

hyperedge_id (str) – ID of the hyperedge for which to get the presence.
as_intervals (bool) – If True, return presence as intervals; if False, return presence as a list of time IDs.

Returns:

A list of time IDs or intervals where the hyperedge is present.

Return type:

List[int | Tuple[int, int]]

Examples

H = ASH()
H.add_hyperedge([1, 2], start=0, end=2)
H.hyperedge_presence('e1')       # [0, 1, 2]
H.hyperedge_presence('e1', True) # [(0, 2)]

node_contribution(node)[source]¶

Calculate the contribution of a node to the ASH, defined as the fraction of temporal snapshots in which the node is present.

Parameters:: node (int) – Node ID for which to calculate the contribution.
Returns:: The contribution of the node as a float between 0 and 1.
Return type:: float

Examples

H = ASH()
# Node 1 present in 1 out of 2 snapshots
H.add_node(1, 0)
H.add_node(2, 1)
H.node_contribution(1)  # 0.5

hyperedge_contribution(hyperedge_id)[source]¶

Calculate the contribution of a hyperedge to the ASH, defined as the fraction of temporal snapshots in which the hyperedge is present.

Parameters:: hyperedge_id (str) – ID of the hyperedge for which to calculate the contribution.
Returns:: The contribution of the hyperedge as a float between 0 and 1
Return type:: float

Examples

H = ASH()
# Edge present in 1 out of 2 snapshots
H.add_hyperedge([1, 2], 0)
H.add_node(3, 1)
H.hyperedge_contribution('e1')  # 0.5

coverage()[source]¶

Calculate the coverage of the ASH, defined as the average number of nodes present across all temporal snapshots, normalized by the total number of nodes.

Returns:: The coverage of the ASH as a float between 0 and 1
Return type:: float

Examples

# Two snapshots, 2 nodes total; average present per snapshot = 1.0 -> coverage 0.5
H = ASH()
H.add_node(1, 0)
H.add_node(2, 1)
H.coverage()  # 0.5

uniformity()[source]¶

Calculate the uniformity of the ASH, defined as the fraction of pairs of nodes that are present together in at least one temporal snapshot, normalized by the total number of pairs.

Returns:: The uniformity of the ASH as a float between 0 and 1
Return type:: float

Examples

# Nodes (1,2) co-present at t=0; (1,3) never; (2,3) co-present at t=1
H = ASH()
H.add_node(1, 0)
H.add_node(2, 0)
H.add_node(2, 1)
H.add_node(3, 1)
u = H.uniformity()  # between 0 and 1

temporal_slice(start, end=None, keep_attrs=True)[source]¶

Create a temporal slice of the ASH from start to end (inclusive). If end is None, the slice will only include the time start. The keep_attrs parameter determines whether to keep node attributes in the slice.

Parameters:

start (int) – Start time of the slice.
end (int | None) – End time of the slice (inclusive). If None, the slice will only include the time start.
keep_attrs (bool) – If True, node attributes are preserved in the slice.

Returns:

A tuple containing the new ASH and a mapping from old hyperedge IDs to new hyperedge IDs.

Return type:

Tuple[ASH, Dict[str, str]]

Examples

H = ASH()
H.add_hyperedge([1, 2], start=0)
H.add_hyperedge([2, 3], start=1)
sub, mapping = H.temporal_slice(0)
isinstance(sub, ASH)  # True

induced_hypergraph(hyperedge_set, keep_attrs=True)[source]¶

Create an induced hypergraph from the ASH using a set of hyperedge IDs. The keep_attrs parameter determines whether to keep node attributes in the new hypergraph.

Parameters:

hyperedge_set (Iterable[str]) – Iterable of hyperedge IDs to include in the induced hypergraph.
keep_attrs (bool) – If True, node attributes are preserved in the new hypergraph.

Returns:

A tuple containing the new ASH and a mapping from old hyperedge IDs to new hyperedge IDs.

Return type:

Tuple[ASH, Dict[str, str]]

Examples

H = ASH()
H.add_hyperedges([[1, 2], [2, 3]], start=0)
sub, mapping = H.induced_hypergraph(['e1'])
set(sub.hyperedges())  # {'e1'} in subgraph namespace

get_s_incident(hyperedge_id, s, start=None, end=None)[source]¶

Get hyperedges that are incident to a given hyperedge with at least s nodes in common within the specified time window. Returns a list of tuples containing hyperedge IDs and the number of nodes they share with the specified hyperedge.

Parameters:

hyperedge_id (str) – ID of the hyperedge to check against.
s (int) – Minimum number of nodes that must be shared with the specified hyperedge.
start (int | None) – Start time of the query. If None, all hyperedges are considered.
end (int | None) – End time of the query (inclusive). If None, only the start time is considered.

Returns:

A list of tuples where each tuple contains a hyperedge ID and the number of nodes it shares with the specified hyperedge.

Return type:

List[Tuple[str, int]]

Examples

H = ASH()
H.add_hyperedges([[1, 2, 3], [1, 3, 4], [4, 5]], start=0)
H.get_s_incident('e1', s=2, start=0)  # [('e2', 2)]

to_dict()[source]¶

Convert the ASH to a dictionary representation. This includes nodes, hyperedges, and their attributes.

Returns:: A dictionary representation of the ASH.
Return type:: Dict[str, Any]

Examples

H = ASH()
H.add_hyperedge([1, 2], start=0)
d = H.to_dict()
set(d.keys())  # {'nodes', 'hedges'}