xgi.stats.nodestats#

Node statistics.

This module is part of the stats package, and it defines node-level statistics. That is, each function defined in this module is assumed to define a node-quantity mapping. Each callable defined here is accessible via a Network object, or a NodeView object. For more details, see the tutorial.

Examples

>>> import xgi
>>> H = xgi.Hypergraph([[1, 2, 3], [2, 3, 4, 5], [3, 4, 5]])
>>> H.degree()
{1: 1, 2: 2, 3: 3, 4: 2, 5: 2}
>>> H.nodes.degree.asdict()
{1: 1, 2: 2, 3: 3, 4: 2, 5: 2}

Functions

attrs(net, bunch, attr=None, missing=None)[source]#

Access node attributes.

Parameters:

  • net (xgi.Hypergraph) – The network.

  • bunch (Iterable) – Nodes in net.

  • attr (str | None (default)) – If None, return all attributes. Otherwise, return a single attribute with name attr.

  • missing (Any) – Value to impute in case a node does not have an attribute with name attr. Default is None.

Returns:

If attr is None, return a nested dict of the form {node: {“attr”: val}}. Otherwise, return a simple dict of the form {node: val}.

Return type:

dict

Notes

When requesting all attributes (i.e. when attr is None), no value is imputed.

Examples

>>> import xgi
>>> H = xgi.Hypergraph([[1, 2, 3], [2, 3, 4, 5], [3, 4, 5]])
>>> H.add_nodes_from([
...         (1, {"color": "red", "name": "horse"}),
...         (2, {"color": "blue", "name": "pony"}),
...         (3, {"color": "yellow", "name": "zebra"}),
...         (4, {"color": "red", "name": "orangutan", "age": 20}),
...         (5, {"color": "blue", "name": "fish", "age": 2}),
...     ])

Access all attributes as different types.

>>> H.nodes.attrs.asdict() 
{1: {'color': 'red', 'name': 'horse'},
 2: {'color': 'blue', 'name': 'pony'},
 3: {'color': 'yellow', 'name': 'zebra'},
 4: {'color': 'red', 'name': 'orangutan', 'age': 20},
 5: {'color': 'blue', 'name': 'fish', 'age': 2}}
>>> H.nodes.attrs.asnumpy() 
array([{'color': 'red', 'name': 'horse'},
       {'color': 'blue', 'name': 'pony'},
       {'color': 'yellow', 'name': 'zebra'},
       {'color': 'red', 'name': 'orangutan', 'age': 20},
       {'color': 'blue', 'name': 'fish', 'age': 2}],
      dtype=object)

Access a single attribute as different types.

>>> H.nodes.attrs('color').asdict()
{1: 'red', 2: 'blue', 3: 'yellow', 4: 'red', 5: 'blue'}
>>> H.nodes.attrs('color').aslist()
['red', 'blue', 'yellow', 'red', 'blue']

By default, None is imputed when a node does not have the requested attribute.

>>> H.nodes.attrs('age').asdict()
{1: None, 2: None, 3: None, 4: 20, 5: 2}

Use missing to change the imputed value.

>>> H.nodes.attrs('age', missing=100).asdict()
{1: 100, 2: 100, 3: 100, 4: 20, 5: 2}
average_neighbor_degree(net, bunch)[source]#

Average neighbor degree.

Parameters:

  • net (xgi.Hypergraph) – The network.

  • bunch (Iterable) – Nodes in net.

Return type:

dict

Examples

>>> import xgi, numpy as np
>>> H = xgi.Hypergraph([[1, 2, 3], [2, 3, 4, 5], [3, 4, 5]])
>>> np.round(H.nodes.average_neighbor_degree.asnumpy(), 3)
array([2.5  , 2.   , 1.75 , 2.333, 2.333])
degree(net, bunch, order=None, weight=None)[source]#

Node degree.

The degree of a node is the number of edges it belongs to.

Parameters:

  • net (xgi.Hypergraph) – The network.

  • bunch (Iterable) – Nodes in net.

  • order (int | None) – If not None (default), only count the edges of the given order.

  • weight (str | None) – If not None, specifies the name of the edge attribute that determines the weight of each edge.

Return type:

dict

clique_eigenvector_centrality(net, bunch, tol=1e-06)[source]#

Clique motif eigenvector centrality of a hypergraph.

See xgi.algorithms.centrality.clique_eigenvector_centrality() for the definition and references.

Parameters:

  • net (xgi.Hypergraph) – The hypergraph of interest.

  • bunch (Iterable) – Nodes in net.

  • tol (float > 0, default: 1e-6) – The desired L2 error in the centrality vector.

Returns:

Centrality, where keys are node IDs and values are centralities.

Return type:

dict

See also

clique_eigenvector_centrality

h_eigenvector_centrality(net, bunch, max_iter=10, tol=1e-06)[source]#

H-eigenvector centrality of a hypergraph.

See xgi.algorithms.centrality.h_eigenvector_centrality() for the definition and references.

Parameters:

  • net (xgi.Hypergraph) – The hypergraph of interest.

  • bunch (Iterable) – Nodes in net.

  • max_iter (int, default: 10) – The maximum number of iterations before the algorithm terminates.

  • tol (float > 0, default: 1e-6) – The desired L2 error in the centrality vector.

Returns:

Centrality, where keys are node IDs and values are centralities.

Return type:

dict

See also

h_eigenvector_centrality

z_eigenvector_centrality(net, bunch, max_iter=10, tol=1e-06)[source]#

Z-eigenvector centrality of a hypergraph.

See xgi.algorithms.centrality.z_eigenvector_centrality() for the definition and references.

Parameters:

  • net (xgi.Hypergraph) – The hypergraph of interest.

  • bunch (Iterable) – Nodes in net.

  • max_iter (int, default: 10) – The maximum number of iterations before the algorithm terminates.

  • tol (float > 0, default: 1e-6) – The desired L2 error in the centrality vector.

Returns:

Centrality, where keys are node IDs and values are centralities.

Return type:

dict

See also

z_eigenvector_centrality

katz_centrality(net, bunch, cutoff=100)[source]#

Katz centrality of a hypergraph.

See xgi.algorithms.centrality.katz_centrality() for the definition, formula, and references.

Parameters:

  • net (xgi.Hypergraph) – The hypergraph of interest.

  • bunch (Iterable) – Nodes in net.

  • cutoff (int) – Power at which to truncate the underlying series. Default 100.

Returns:

Node IDs are keys and centrality values are values (1-normalized).

Return type:

dict

Raises:

XGIError – If the hypergraph is empty.

See also

katz_centrality

node_edge_centrality(net, bunch, f=<function <lambda>>, g=<function <lambda>>, phi=<function <lambda>>, psi=<function <lambda>>, max_iter=100, tol=1e-06)[source]#

Node component of the nonlinear node-edge centrality.

See xgi.algorithms.centrality.node_edge_centrality() for the definition, parameters, and references.

Parameters:

  • net (Hypergraph) – The hypergraph of interest.

  • bunch (Iterable) – Nodes in net.

Returns:

Node centralities.

Return type:

dict

See also

node_edge_centrality

clustering_coefficient(net, bunch)[source]#

Clustering coefficient based on the pairwise projection of the hypergraph.

See xgi.algorithms.clustering.clustering_coefficient() for the definition, formula, and references.

Parameters:

  • net (xgi.Hypergraph) – The network.

  • bunch (Iterable) – Nodes in net.

Return type:

dict

See also

clustering_coefficient, local_clustering_coefficient, two_node_clustering_coefficient

local_clustering_coefficient(net, bunch)[source]#

Local clustering coefficient based on edge overlap.

See xgi.algorithms.clustering.local_clustering_coefficient() for the definition and references.

Parameters:

  • net (xgi.Hypergraph) – The network.

  • bunch (Iterable) – Nodes in net.

Returns:

keys are node IDs and values are the clustering coefficients.

Return type:

dict

See also

local_clustering_coefficient, clustering_coefficient, two_node_clustering_coefficient

two_node_clustering_coefficient(net, bunch, kind='union')[source]#

Average over all two-node clustering coefficients involving each node.

See xgi.algorithms.clustering.two_node_clustering_coefficient() for the definition and references.

Parameters:

  • net (xgi.Hypergraph) – The network.

  • bunch (Iterable) – Nodes in net.

  • kind (str) – The type of two-node clustering coefficient: “union”, “min”, or “max”. By default, “union”.

Returns:

nodes are keys, clustering coefficients are values.

Return type:

dict

See also

two_node_clustering_coefficient, clustering_coefficient, local_clustering_coefficient

local_simplicial_fraction(net, bunch, min_size=2, exclude_min_size=True)[source]#

The local simplicial fraction.

For each node, computes xgi.algorithms.simpliciality.simplicial_fraction() on the subhypergraph induced by the node and its neighbors.

Parameters:

  • net (xgi.Hypergraph) – The network.

  • bunch (Iterable) – Nodes in net.

  • min_size (int, default: 2) – The minimum hyperedge size to include when calculating whether a hyperedge is a simplex by counting subfaces.

  • exclude_min_size (bool, optional) – Whether to include minimal simplices when counting simplices, by default True

Return type:

dict

See also

simplicial_fraction

References

“The simpliciality of higher-order order networks” by Nicholas Landry, Jean-Gabriel Young, and Nicole Eikmeier, EPJ Data Science 13, 17 (2024).

local_edit_simpliciality(net, bunch, min_size=2, exclude_min_size=True)[source]#

The local edit simpliciality.

For each node, computes xgi.algorithms.simpliciality.edit_simpliciality() on the subhypergraph induced by the node and its neighbors.

Parameters:

  • net (xgi.Hypergraph) – The network.

  • bunch (Iterable) – Nodes in net.

  • min_size (int, default: 2) – The minimum hyperedge size to include when calculating whether a hyperedge is a simplex by counting subfaces.

  • exclude_min_size (bool, optional) – Whether to include minimal simplices when counting simplices, by default True

Return type:

dict

See also

edit_simpliciality

References

“The simpliciality of higher-order order networks” by Nicholas Landry, Jean-Gabriel Young, and Nicole Eikmeier, EPJ Data Science 13, 17 (2024).

local_face_edit_simpliciality(net, bunch, min_size=2, exclude_min_size=True)[source]#

The local face edit simpliciality.

For each node, computes xgi.algorithms.simpliciality.face_edit_simpliciality() on the subhypergraph induced by the node and its neighbors.

Parameters:

  • net (xgi.Hypergraph) – The network.

  • bunch (Iterable) – Nodes in net.

  • min_size (int, default: 2) – The minimum hyperedge size to include when calculating whether a hyperedge is a simplex by counting subfaces.

  • exclude_min_size (bool, optional) – Whether to include minimal simplices when counting simplices, by default True

Return type:

dict

See also

face_edit_simpliciality

References

“The simpliciality of higher-order order networks” by Nicholas Landry, Jean-Gabriel Young, and Nicole Eikmeier, EPJ Data Science 13, 17 (2024).