easygraph.classes.base module#

Bases: object

The BaseHypergraph class is the base class for all hypergraph structures.

Parameters:

num_v (int) – The number of vertices.
e_list (Union[List[int], List[List[int]]], optional) – Edge list. Defaults to None.
e_weight (Union[float, List[float]], optional) – A list of weights for edges. Defaults to None.
extra_selfloop (bool, optional) – Whether to add extra self-loop to the graph. Defaults to False.
device (torch.device, optional) – The device to store the graph. Defaults to torch.device('cpu').

Attributes:

H: Return the hypergraph incidence matrix.
H_e2v: Return the hypergraph incidence matrix with sparse matrix format.
H_of_group: Return the hypergraph incidence matrix in the specified hyperedge group.
H_v2e: Return the hypergraph incidence matrix with sparse matrix format.
R_e2v: Return the weight matrix of connections (hyperedges point to vertices) with sparse matrix format.
R_v2e: Return the weight matrix of connections (vertices point to hyperedges) with sparse matrix format.
W_e: Return the hyperedge weight matrix of the hypergraph.
W_v: Return the vertex weight matrix of the hypergraph.
e: Return all hyperedges and weights in the hypergraph.
e_property
group_names: Return the names of hyperedge groups in the hypergraph.
num_e: Return the number of hyperedges in the hypergraph.
num_groups: Return the number of hyperedge groups in the hypergraph.
num_v: Return the number of vertices in the hypergraph.
state_dict: Get the state dict of the hypergraph.
v: Return the list of vertices.
v_property
v_weight: Return the vertex weights of the hypergraph.
vars_for_DL: Return a name list of available variables for deep learning in this type of hypergraph.

Methods

`H_e2v_of_group`(group_name)	Return the hypergraph incidence matrix with `sparse matrix` format in the specified hyperedge group.
`H_v2e_of_group`(group_name)	Return the hypergraph incidence matrix with `sparse matrix` format in the specified hyperedge group.
`R_e2v_of_group`(group_name)	Return the weight matrix of connections (hyperedges point to vertices) with `sparse matrix` format in the specified hyperedge group.
`R_v2e_of_group`(group_name)	Return the weight matrix of connections (vertices point to hyperedges) with `sparse matrix` format in the specified hyperedge group.
`W_e_of_group`(group_name)	Return the hyperedge weight matrix of the specified hyperedge group.
`add_hyperedges`(e_list_v2e, e_list_e2v[, ...])	Add hyperedges to the hypergraph.
`clear`()	Remove all hyperedges and caches from the hypergraph.
`clone`()	Return a copy of this type of hypergraph.
`draw`(**kwargs)	Draw the structure.
`drop_hyperedges`(drop_rate[, ord])	Randomly drop hyperedges from the hypergraph.
`drop_hyperedges_of_group`(group_name, drop_rate)	Randomly drop hyperedges from the specified hyperedge group.
`e2v`(X[, aggr, e2v_weight, v_weight])	Message passing of `hyperedges to vertices`.
`e2v_aggregation`(X[, aggr, e2v_weight])	Message aggregation step of `hyperedges to vertices`.
`e2v_aggregation_of_group`(group_name, X[, ...])	Message aggregation step of `hyperedges to vertices` in specified hyperedge group.
`e2v_of_group`(group_name, X[, aggr, ...])	Message passing of `hyperedges to vertices` in specified hyperedge group.
`e2v_update`(X[, v_weight])	Message update step of `hyperedges to vertices`.
`e2v_update_of_group`(group_name, X[, v_weight])	Message update step of `hyperedges to vertices` in specified hyperedge group.
`e_of_group`(group_name)	Return all hyperedges and weights in the specified hyperedge group.
`from_state_dict`(state_dict)	Load the EasyGraph's hypergraph structure from the state dict.
`load`(file_path)	Load the EasyGraph's hypergraph structure from a file.
`num_e_of_group`(group_name)	Return the number of hyperedges in the specified hyperedge group.
`remove_hyperedges`(e_list_v2e, e_list_e2v[, ...])	Remove the specified hyperedges from the hypergraph.
`save`(file_path)	Save the EasyGraph's hypergraph structure to a file.
`smoothing`(X, L, lamb)	Spectral-based smoothing.
`to`([device])	Move the hypergraph to the specified device.
`v2e`(X[, aggr, v2e_weight, e_weight])	Message passing of `vertices to hyperedges`.
`v2e_aggregation`(X[, aggr, v2e_weight, drop_rate])	Message aggretation step of `vertices to hyperedges`.
`v2e_aggregation_of_group`(group_name, X[, ...])	Message aggregation step of `vertices to hyperedges` in specified hyperedge group.
`v2e_of_group`(group_name, X[, aggr, ...])	Message passing of `vertices to hyperedges` in specified hyperedge group.
`v2e_update`(X[, e_weight])	Message update step of `vertices to hyperedges`.
`v2e_update_of_group`(group_name, X[, e_weight])	Message update step of `vertices to hyperedges` in specified hyperedge group.
`v2v`(X[, aggr, v2e_aggr, v2e_weight, ...])	Message passing of `vertices to vertices`.
`v2v_of_group`(group_name, X[, aggr, ...])	Message passing of `vertices to vertices` in specified hyperedge group.

abstract property H: Tensor#: Return the hypergraph incidence matrix.

property H_e2v: Tensor#: Return the hypergraph incidence matrix with sparse matrix format.

H_e2v_of_group(group_name: str) → Tensor[source]#

Return the hypergraph incidence matrix with sparse matrix format in the specified hyperedge group.

Parameters:: group_name (str) – The name of the specified hyperedge group.

abstract property H_of_group: Tensor#

Return the hypergraph incidence matrix in the specified hyperedge group.

Parameters:: group_name (str) – The name of the specified hyperedge group.

property H_v2e: Tensor#: Return the hypergraph incidence matrix with sparse matrix format.

H_v2e_of_group(group_name: str) → Tensor[source]#

Return the hypergraph incidence matrix with sparse matrix format in the specified hyperedge group.

Parameters:: group_name (str) – The name of the specified hyperedge group.

property R_e2v: Tensor#: Return the weight matrix of connections (hyperedges point to vertices) with sparse matrix format.

R_e2v_of_group(group_name: str) → Tensor[source]#

Return the weight matrix of connections (hyperedges point to vertices) with sparse matrix format in the specified hyperedge group.

Parameters:: group_name (str) – The name of the specified hyperedge group.

property R_v2e: Tensor#: Return the weight matrix of connections (vertices point to hyperedges) with sparse matrix format.

R_v2e_of_group(group_name: str) → Tensor[source]#

Return the weight matrix of connections (vertices point to hyperedges) with sparse matrix format in the specified hyperedge group.

Parameters:: group_name (str) – The name of the specified hyperedge group.

property W_e: Tensor#: Return the hyperedge weight matrix of the hypergraph.

W_e_of_group(group_name: str) → Tensor[source]#

Return the hyperedge weight matrix of the specified hyperedge group.

Parameters:: group_name (str) – The name of the specified hyperedge group.

property W_v: Tensor#: Return the vertex weight matrix of the hypergraph.

Add hyperedges to the hypergraph. If the group_name is not specified, the hyperedges will be added to the default main hyperedge group.

Parameters:

num_v (int) – The number of vertices in the hypergraph.
e_list_v2e (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the vertices point to the hyperedges.
e_list_e2v (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the hyperedges point to the vertices.
w_list_v2e (Union[List[float], List[List[float]]], optional) – The weights are attached to the connections from vertices to hyperedges, which has the same shape as e_list_v2e. If set to None, the value 1 is used for all connections. Defaults to None.
w_list_e2v (Union[List[float], List[List[float]]], optional) – The weights are attached to the connections from the hyperedges to the vertices, which has the same shape to e_list_e2v. If set to None, the value 1 is used for all connections. Defaults to None.
e_weight (Union[float, List[float]], optional) – A list of weights for hyperedges. If set to None, the value 1 is used for all hyperedges. Defaults to None.
merge_op (str) – The merge operation for the conflicting hyperedges. The possible values are mean, sum, max, and min. Defaults to mean.
group_name (str, optional) – The target hyperedge group to add these hyperedges. Defaults to the main hyperedge group.

clear()[source]#: Remove all hyperedges and caches from the hypergraph.

abstract clone() → BaseHypergraph[source]#: Return a copy of this type of hypergraph.

abstract draw(**kwargs)[source]#: Draw the structure.

abstract drop_hyperedges(drop_rate: float, ord='uniform')[source]#

Randomly drop hyperedges from the hypergraph. This function will return a new hypergraph with non-dropped hyperedges.

Parameters:

drop_rate (float) – The drop rate of hyperedges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

abstract drop_hyperedges_of_group(group_name: str, drop_rate: float, ord='uniform')[source]#

Randomly drop hyperedges from the specified hyperedge group. This function will return a new hypergraph with non-dropped hyperedges.

Parameters:

group_name (str) – The name of the hyperedge group.
drop_rate (float) – The drop rate of hyperedges.
ord (str) – The order of dropping edges. Currently, only 'uniform' is supported. Defaults to uniform.

abstract property e: Tuple[List[List[int]], List[float]]#: Return all hyperedges and weights in the hypergraph.

abstract e2v(X: Tensor, aggr: str = 'mean', e2v_weight: Tensor | None = None, v_weight: Tensor | None = None)[source]#

Message passing of hyperedges to vertices. The combination of e2v_aggregation and e2v_update.

Parameters:

X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_aggregation(X: Tensor, aggr: str = 'mean', e2v_weight: Tensor | None = None)[source]#

Message aggregation step of hyperedges to vertices.

Parameters:

X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_aggregation_of_group(group_name: str, X: Tensor, aggr: str = 'mean', e2v_weight: Tensor | None = None)[source]#

Message aggregation step of hyperedges to vertices in specified hyperedge group.

Parameters:

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_of_group(group_name: str, X: Tensor, aggr: str = 'mean', e2v_weight: Tensor | None = None, v_weight: Tensor | None = None)[source]#

Message passing of hyperedges to vertices in specified hyperedge group. The combination of e2v_aggregation_of_group and e2v_update_of_group.

Parameters:

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_update(X: Tensor, v_weight: Tensor | None = None)[source]#

Message update step of hyperedges to vertices.

Parameters:

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e2v_update_of_group(group_name: str, X: Tensor, v_weight: Tensor | None = None)[source]#

Message update step of hyperedges to vertices in specified hyperedge group.

Parameters:

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract e_of_group(group_name: str) → Tuple[List[List[int]], List[float]][source]#

Return all hyperedges and weights in the specified hyperedge group.

Parameters:: group_name (str) – The name of the specified hyperedge group.

property e_property#

abstract static from_state_dict(state_dict: dict)[source]#

Load the EasyGraph’s hypergraph structure from the state dict.

Parameters:: state_dict (dict) – The state dict to load the EasyGraph’s hypergraph.

property group_names: List[str]#: Return the names of hyperedge groups in the hypergraph.

abstract static load(file_path: str | Path)[source]#

Load the EasyGraph’s hypergraph structure from a file.

Parameters:: file_path (str) – The file path to load the DEasyGraph’s hypergraph structure.

property num_e: int#: Return the number of hyperedges in the hypergraph.

num_e_of_group(group_name: str) → int[source]#

Return the number of hyperedges in the specified hyperedge group.

Parameters:: group_name (str) – The name of the specified hyperedge group.

property num_groups: int#: Return the number of hyperedge groups in the hypergraph.

property num_v: int#: Return the number of vertices in the hypergraph.

remove_hyperedges(e_list_v2e: List[int] | List[List[int]], e_list_e2v: List[int] | List[List[int]], group_name: str | None = None)[source]#

Remove the specified hyperedges from the hypergraph.

Parameters:

e_list_v2e (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the vertices point to the hyperedges.
e_list_e2v (Union[List[int], List[List[int]]]) – A list of hyperedges describes how the hyperedges point to the vertices.
group_name (str, optional) – Remove these hyperedges from the specified hyperedge group. If not specified, the function will remove those hyperedges from all hyperedge groups. Defaults to the None.

abstract save(file_path: str | Path)[source]#

Save the EasyGraph’s hypergraph structure to a file.

Parameters:: file_path (str) – The file_path to store the EasyGraph’s hypergraph structure.

smoothing(X: Tensor, L: Tensor, lamb: float) → Tensor[source]#

Spectral-based smoothing.

\[X_{smoothed} = X + \lambda \mathcal{L} X\]

Parameters:

X (torch.Tensor) – The vertex feature matrix. Size \((|\mathcal{V}|, C)\).
L (torch.Tensor) – The Laplacian matrix with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).
lamb (float) – \(\lambda\), the strength of smoothing.

abstract property state_dict: Dict[str, Any]#: Get the state dict of the hypergraph.

to(device: str = 'cpu') → BaseHypergraph[source]#

Move the hypergraph to the specified device.

Parameters:: device (torch.device) – The device to store the hypergraph.

property v: List[int]#: Return the list of vertices.

abstract v2e(X: Tensor, aggr: str = 'mean', v2e_weight: Tensor | None = None, e_weight: Tensor | None = None)[source]#

Message passing of vertices to hyperedges. The combination of v2e_aggregation and v2e_update.

Parameters:

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_aggregation(X: Tensor, aggr: str = 'mean', v2e_weight: Tensor | None = None, drop_rate: float = 0.0)[source]#

Message aggretation step of vertices to hyperedges.

Parameters:

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_aggregation_of_group(group_name: str, X: Tensor, aggr: str = 'mean', v2e_weight: Tensor | None = None, drop_rate: float = 0.0)[source]#

Message aggregation step of vertices to hyperedges in specified hyperedge group.

Parameters:

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_of_group(group_name: str, X: Tensor, aggr: str = 'mean', v2e_weight: Tensor | None = None, e_weight: Tensor | None = None)[source]#

Message passing of vertices to hyperedges in specified hyperedge group. The combination of e2v_aggregation_of_group and e2v_update_of_group.

Parameters:

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_update(X: Tensor, e_weight: Tensor | None = None)[source]#

Message update step of vertices to hyperedges.

Parameters:

X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

abstract v2e_update_of_group(group_name: str, X: Tensor, e_weight: Tensor | None = None)[source]#

Message update step of vertices to hyperedges in specified hyperedge group.

Parameters:

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Hyperedge feature matrix. Size \((|\mathcal{E}|, C)\).
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

Message passing of vertices to vertices. The combination of v2e and e2v.

Parameters:

X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, this aggr will be used to both v2e and e2v.
v2e_aggr (str, optional) – The aggregation method for hyperedges to vertices. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in e2v.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e2v_aggr (str, optional) – The aggregation method for vertices to hyperedges. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in v2e.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

Message passing of vertices to vertices in specified hyperedge group. The combination of v2e_of_group and e2v_of_group.

Parameters:

group_name (str) – The specified hyperedge group.
X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).
aggr (str) – The aggregation method. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, this aggr will be used to both v2e_of_group and e2v_of_group.
v2e_aggr (str, optional) – The aggregation method for hyperedges to vertices. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in e2v_of_group.
v2e_weight (torch.Tensor, optional) – The weight vector attached to connections (vertices point to hyepredges). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e_weight (torch.Tensor, optional) – The hyperedge weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
e2v_aggr (str, optional) – The aggregation method for vertices to hyperedges. Can be 'mean', 'sum' and 'softmax_then_sum'. If specified, it will override the aggr in v2e_of_group.
e2v_weight (torch.Tensor, optional) – The weight vector attached to connections (hyperedges point to vertices). If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.
v_weight (torch.Tensor, optional) – The vertex weight vector. If not specified, the function will use the weights specified in hypergraph construction. Defaults to None.

property v_property#

property v_weight: List[float]#: Return the vertex weights of the hypergraph.

abstract property vars_for_DL: List[str]#: Return a name list of available variables for deep learning in this type of hypergraph.

easygraph.classes.base.load_structure(file_path: str | Path)[source]#

Load a EasyGraph’s high-order network structure from a file. The supported structure Hypergraph.

Parameters:: file_path (Union[str, Path]) – The file path to load the EasyGraph’s structure.