xgi.algorithms.simpliciality#

Functions

edit_simpliciality(H, min_size=2, exclude_min_size=True)[source]#

Computes the edit simpliciality.

The fraction of sub-edges contained when compared to a simplicial complex.

Parameters:

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

  • min_size (int, optional) – The minimum hyperedge size to include when calculating whether a hyperedge is a simplex by counting subfaces. For more details, see the Notes below. By default, 2.

  • exclude_min_size (bool, optional) – Whether to exclude minimal simplices when counting simplices. For more detailed information, see the Notes below. By default, True.

Returns:

The edit simpliciality

Return type:

float

See also

simplicial_edit_distance

Notes

1. The formal definition of a simplicial complex can be unnecessarily strict when used to represent perfect inclusion structures. By definition, a simplex always contains singletons (edges comprising a single node) and the empty set. Several datasets will not include such interactions by construction. To circumvent this issue, we use a relaxed definition of downward closure that excludes edges of a certain size or smaller wherever it makes sense. By default, we set the minimum size to be 2 since some datasets do not contain singletons.

2. Hyperedges we call “minimal faces” may significantly skew the simpliciality of a dataset. The minimal faces of a hypergraph \(H\) are the edges of the minimal size, i.e., \(|e| = \min(K)\), where \(K\) is the set of sizes that we consider based on note 1. (In a traditional simplicial complex, the minimal faces are singletons). With the size restrictions in place, the minimal faces of a hypergraph are always simplices because, by definition, there are no smaller edges for these edges to include. When measuring the simpliciality of a dataset, it is most meaningful to focus on the faces for which inclusion is possible, and so, by default, we exclude these minimal faces when counting potential simplices.

References

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

simplicial_edit_distance(H, min_size=2, exclude_min_size=True, normalize=True)[source]#

Computes the simplicial edit distance.

The number (or fraction) of sub-edges needed to be added to a hypergraph to make it a simplicial complex.

Parameters:

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

  • min_size (int, optional) – The minimum hyperedge size to include when calculating whether a hyperedge is a simplex by counting subfaces. For more details, see the Notes below. By default, 2.

  • exclude_min_size (bool, optional) – Whether to exclude minimal simplices when counting simplices. For more detailed information, see the Notes below. By default, True.

  • normalize (bool, optional) – Whether to normalize by the total number of edges

Returns:

The edit simpliciality

Return type:

float

See also

edit_simpliciality

Notes

1. The formal definition of a simplicial complex can be unnecessarily strict when used to represent perfect inclusion structures. By definition, a simplex always contains singletons (edges comprising a single node) and the empty set. Several datasets will not include such interactions by construction. To circumvent this issue, we use a relaxed definition of downward closure that excludes edges of a certain size or smaller wherever it makes sense. By default, we set the minimum size to be 2 since some datasets do not contain singletons.

2. Hyperedges we call “minimal faces” may significantly skew the simpliciality of a dataset. The minimal faces of a hypergraph \(H\) are the edges of the minimal size, i.e., \(|e| = \min(K)\), where \(K\) is the set of sizes that we consider based on note 1. (In a traditional simplicial complex, the minimal faces are singletons). With the size restrictions in place, the minimal faces of a hypergraph are always simplices because, by definition, there are no smaller edges for these edges to include. When measuring the simpliciality of a dataset, it is most meaningful to focus on the faces for which inclusion is possible, and so, by default, we exclude these minimal faces when counting potential simplices.

References

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

face_edit_simpliciality(H, min_size=2, exclude_min_size=True)[source]#

Computes the face edit simpliciality.

The average fraction of sub-edges contained in a hyperedge relative to a simplex.

Parameters:

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

  • min_size (int, optional) – The minimum hyperedge size to include when calculating whether a hyperedge is a simplex by counting subfaces. For more details, see the Notes below. By default, 2.

  • exclude_min_size (bool, optional) – Whether to exclude minimal simplices when counting simplices. For more detailed information, see the Notes below. By default, True.

Returns:

The face edit simpliciality

Return type:

float

See also

mean_face_edit_distance

Notes

1. The formal definition of a simplicial complex can be unnecessarily strict when used to represent perfect inclusion structures. By definition, a simplex always contains singletons (edges comprising a single node) and the empty set. Several datasets will not include such interactions by construction. To circumvent this issue, we use a relaxed definition of downward closure that excludes edges of a certain size or smaller wherever it makes sense. By default, we set the minimum size to be 2 since some datasets do not contain singletons.

2. Hyperedges we call “minimal faces” may significantly skew the simpliciality of a dataset. The minimal faces of a hypergraph \(H\) are the edges of the minimal size, i.e., \(|e| = \min(K)\), where \(K\) is the set of sizes that we consider based on note 1. (In a traditional simplicial complex, the minimal faces are singletons). With the size restrictions in place, the minimal faces of a hypergraph are always simplices because, by definition, there are no smaller edges for these edges to include. When measuring the simpliciality of a dataset, it is most meaningful to focus on the faces for which inclusion is possible, and so, by default, we exclude these minimal faces when counting potential simplices.

References

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

mean_face_edit_distance(H, min_size=2, exclude_min_size=True, normalize=True)[source]#

Computes the mean face edit distance

The average number (or fraction) of sub-edges needed to be added to make a hyperedge a simplex.

Parameters:

  • H (Hypergraph) – The hypergraph of interest

  • min_size (int, optional) – The minimum hyperedge size to include when calculating whether a hyperedge is a simplex by counting subfaces. For more details, see the Notes below. By default, 2.

  • exclude_min_size (bool, optional) – Whether to exclude minimal simplices when counting simplices. For more detailed information, see the Notes below. By default, True.

  • normalize (bool, optional) – Whether to normalize the face edit distance, by default True

Returns:

The mean face edit distance

Return type:

float

See also

face_edit_simpliciality

Notes

1. The formal definition of a simplicial complex can be unnecessarily strict when used to represent perfect inclusion structures. By definition, a simplex always contains singletons (edges comprising a single node) and the empty set. Several datasets will not include such interactions by construction. To circumvent this issue, we use a relaxed definition of downward closure that excludes edges of a certain size or smaller wherever it makes sense. By default, we set the minimum size to be 2 since some datasets do not contain singletons.

2. Hyperedges we call “minimal faces” may significantly skew the simpliciality of a dataset. The minimal faces of a hypergraph \(H\) are the edges of the minimal size, i.e., \(|e| = \min(K)\), where \(K\) is the set of sizes that we consider based on note 1. (In a traditional simplicial complex, the minimal faces are singletons). With the size restrictions in place, the minimal faces of a hypergraph are always simplices because, by definition, there are no smaller edges for these edges to include. When measuring the simpliciality of a dataset, it is most meaningful to focus on the faces for which inclusion is possible, and so, by default, we exclude these minimal faces when counting potential simplices.

References

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

simplicial_fraction(H, min_size=2, exclude_min_size=True)[source]#

Computing the simplicial fraction for a hypergraph.

What fraction of the hyperedges are simplices?

Parameters:

  • H (Hypergraph) – The hypergraph of interest

  • min_size (int, optional) – The minimum hyperedge size to include when calculating whether a hyperedge is a simplex by counting subfaces. For more details, see the Notes below. By default, 2.

  • exclude_min_size (bool, optional) – Whether to exclude minimal simplices when counting simplices. For more detailed information, see the Notes below. By default, True.

Returns:

The simplicial fraction

Return type:

float

Notes

1. The formal definition of a simplicial complex can be unnecessarily strict when used to represent perfect inclusion structures. By definition, a simplex always contains singletons (edges comprising a single node) and the empty set. Several datasets will not include such interactions by construction. To circumvent this issue, we use a relaxed definition of downward closure that excludes edges of a certain size or smaller wherever it makes sense. By default, we set the minimum size to be 2 since some datasets do not contain singletons.

2. Hyperedges we call “minimal faces” may significantly skew the simpliciality of a dataset. The minimal faces of a hypergraph \(H\) are the edges of the minimal size, i.e., \(|e| = \min(K)\), where \(K\) is the set of sizes that we consider based on note 1. (In a traditional simplicial complex, the minimal faces are singletons). With the size restrictions in place, the minimal faces of a hypergraph are always simplices because, by definition, there are no smaller edges for these edges to include. When measuring the simpliciality of a dataset, it is most meaningful to focus on the faces for which inclusion is possible, and so, by default, we exclude these minimal faces when counting potential simplices.

References

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