delaynet.network_analysis package

delaynet.network_analysis package#

Submodules#

delaynet.network_analysis.metrics module#

Basic network metrics for delaynet.

This module provides functions to compute fundamental network metrics from reconstructed and potentially pruned networks.

delaynet.network_analysis.metrics.betweenness_centrality(weight_matrix: ndarray, directed: bool = True, normalize: bool = True) → ndarray[source]#

Compute betweenness centrality for each node in the network.

Betweenness centrality measures how often a node lies on the shortest paths between other nodes in the network.

Parameters:

  • weight_matrix (numpy.ndarray, shape (n_nodes, n_nodes)) – Matrix of connection weights. Non-zero values indicate connections. For weighted networks, weights are interpreted as connection strengths.

  • directed (bool) – If True, treat the network as directed.

  • normalize (bool) – If True, normalize by the maximum possible betweenness (scaling).

  • normalise (bool | None) – If True, return a z-score by comparing the metric value to an ensemble of directed random graphs with the same number of nodes and links (G(n,m)). If False or None, the metric is computed without normalisation (default).

  • n_random (int) – Number of random realisations for the null ensemble. Only valid when normalise=True. Default is 20.

  • random_seed (int | None) – Random seed for reproducibility of the null ensemble. Only valid when normalise=True.

Returns:

Array of betweenness centrality values for each node, or the corresponding z-scores if normalise=True.

Return type:

numpy.ndarray, shape (n_nodes,)

Raises:

  • ValueError – If weight_matrix is not square.

  • ValueError – If normalise is False or None and normalisation parameters (n_random or random_seed) are provided.

  • ValueError – If normalise=True and weight_matrix is not strictly binary (values must be in {0,1}). Weighted normalisation is not supported.

  • ValueError – If normalise=True and the diagonal of weight_matrix is not zero (no self-loops are assumed).

Normalisation details:

  • The null model is a directed Erdos–Rényi G(n,m) ensemble with the same number of nodes and links as the input network, sampled using igraph.Graph.Erdos_Renyi() with directed=True and loops=False.

  • The returned value is a z-score: z = (x_true − μ_null) / σ_null (element-wise).

  • If σ_null = 0 at any position, the returned z-score at that position is NaN.

Example:#

>>> import numpy as np
>>> from delaynet.network_analysis.metrics import betweenness_centrality
>>> # Example binary adjacency matrix
>>> weights = np.array([[0, 1, 0], [1, 0, 1], [0, 1, 0]])
>>> centrality = betweenness_centrality(weights)
>>> centrality.shape
(3,)
delaynet.network_analysis.metrics.eigenvector_centrality(weight_matrix: ndarray, directed: bool = True) → ndarray[source]#

Compute eigenvector centrality for each node in the network.

Eigenvector centrality measures the influence of a node in a network. It assigns relative scores to all nodes based on the concept that connections to high-scoring nodes contribute more to the score of the node in question than equal connections to low-scoring nodes.

Parameters:

  • weight_matrix (numpy.ndarray, shape (n_nodes, n_nodes)) – Matrix of connection weights. Non-zero values indicate connections.

  • directed (bool) – If True, treat the network as directed.

  • normalise (bool | None) – If True, return z-scores by comparing the metric values to an ensemble of directed random graphs with the same number of nodes and links (G(n,m)). If False or None, the metric is computed without normalisation (default).

  • n_random (int) – Number of random realisations for the null ensemble. Only valid when normalise=True. Default is 20.

  • random_seed (int | None) – Random seed for reproducibility of the null ensemble. Only valid when normalise=True.

Returns:

Array of eigenvector centrality values for each node, or the corresponding z-scores if normalise=True.

Return type:

numpy.ndarray, shape (n_nodes,)

Raises:

  • ValueError – If weight_matrix is not square.

  • ValueError – If normalise is False or None and normalisation parameters (n_random or random_seed) are provided.

  • ValueError – If normalise=True and weight_matrix is not strictly binary (values must be in {0,1}). Weighted normalisation is not supported.

  • ValueError – If normalise=True and the diagonal of weight_matrix is not zero (no self-loops are assumed).

Normalisation details:

  • The null model is a directed Erdos–Rényi G(n,m) ensemble with the same number of nodes and links as the input network, sampled using igraph.Graph.Erdos_Renyi() with directed=True and loops=False.

  • The returned value is a z-score: z = (x_true − μ_null) / σ_null (element-wise).

  • If σ_null = 0 at any position, the returned z-score at that position is NaN.

Example:#

>>> import numpy as np
>>> from delaynet.network_analysis.metrics import eigenvector_centrality
>>> # Example binary adjacency matrix
>>> weights = np.array([[0, 1, 1], [1, 0, 1], [1, 1, 0]])
>>> centrality = eigenvector_centrality(weights)
>>> centrality.shape
(3,)
delaynet.network_analysis.metrics.global_efficiency(weight_matrix: ndarray, directed: bool = True) → float[source]#

Compute the global efficiency of the network.

Global efficiency is the average of the inverse shortest path lengths between all pairs of nodes. It measures how efficiently information can be exchanged over the network.

Parameters:

  • weight_matrix (numpy.ndarray, shape (n_nodes, n_nodes)) – Matrix of connection weights. Non-zero values indicate connections. For weighted networks, weights are interpreted as connection strengths.

  • directed (bool) – If True, treat the network as directed.

  • normalise (bool | None) – If True, return a z-score by comparing the metric value to an ensemble of directed random graphs with the same number of nodes and links (G(n,m)). If False or None, the metric is computed without normalisation (default).

  • n_random (int) – Number of random realisations for the null ensemble. Only valid when normalise=True. Default is 20.

  • random_seed (int | None) – Random seed for reproducibility of the null ensemble. Only valid when normalise=True.

Returns:

Global efficiency value between 0 and 1, or the corresponding z-score if normalise=True.

Return type:

float

Raises:

  • ValueError – If weight_matrix is not square.

  • ValueError – If normalise is False or None and normalisation parameters (n_random or random_seed) are provided.

  • ValueError – If normalise=True and weight_matrix is not strictly binary (values must be in {0,1}). Weighted normalisation is not supported.

  • ValueError – If normalise=True and the diagonal of weight_matrix is not zero (no self-loops are assumed).

Normalisation details:

  • The null model is a directed Erdos–Rényi G(n,m) ensemble with the same number of nodes and links as the input network, sampled using igraph.Graph.Erdos_Renyi() with directed=True and loops=False.

  • The returned value is a z-score: z = (x_true − μ_null) / σ_null.

  • If σ_null = 0 at any position, the returned z-score at that position is NaN.

Example:#

>>> import numpy as np
>>> from delaynet.network_analysis.metrics import global_efficiency
>>> # Example binary adjacency matrix
>>> weights = np.array([[0, 1, 1], [1, 0, 1], [1, 1, 0]])
>>> efficiency = global_efficiency(weights)
>>> isinstance(efficiency, float)
True
delaynet.network_analysis.metrics.isolated_nodes_inbound(weight_matrix: ndarray) → int[source]#

Count the number of nodes with no inbound links.

These are nodes that do not receive delays from other nodes.

Parameters:

  • weight_matrix (numpy.ndarray, shape (n_nodes, n_nodes)) – Matrix of connection weights. Non-zero values indicate connections. Rows represent sources, columns represent targets.

  • normalise (bool | None) – If True, return a z-score by comparing the metric value to an ensemble of directed random graphs with the same number of nodes and links (G(n,m)). If False or None, the metric is computed without normalisation (default).

  • n_random (int) – Number of random realisations for the null ensemble. Only valid when normalise=True. Default is 20.

  • random_seed (int | None) – Random seed for reproducibility of the null ensemble. Only valid when normalise=True.

Returns:

Number of nodes with no inbound connections, or the corresponding z-score if normalise=True.

Return type:

int | float

Raises:

  • ValueError – If weight_matrix is not square.

  • ValueError – If normalise is False or None and normalisation parameters (n_random or random_seed) are provided.

  • ValueError – If normalise=True and weight_matrix is not strictly binary (values must be in {0,1}). Weighted normalisation is not supported.

  • ValueError – If normalise=True and the diagonal of weight_matrix is not zero (no self-loops are assumed).

Normalisation details:

  • The null model is a directed Erdos–Rényi G(n,m) ensemble with the same number of nodes and links as the input network, sampled using igraph.Graph.Erdos_Renyi() with directed=True and loops=False.

  • The returned value is a z-score: z = (x_true − μ_null) / σ_null.

  • If σ_null = 0 at any position, the returned z-score at that position is NaN.

Example:#

>>> import numpy as np
>>> from delaynet.network_analysis.metrics import isolated_nodes_inbound
>>> # Example adjacency matrix
>>> weights = np.array([[0, 1, 0], [0, 0, 1], [0, 0, 0]])
>>> count = isolated_nodes_inbound(weights)
>>> isinstance(count, int)
True
delaynet.network_analysis.metrics.isolated_nodes_outbound(weight_matrix: ndarray) → int[source]#

Count the number of nodes with no outbound links.

These are nodes that do not propagate delays to other nodes, they just receive them.

Parameters:

  • weight_matrix (numpy.ndarray, shape (n_nodes, n_nodes)) – Matrix of connection weights. Non-zero values indicate connections. Rows represent sources, columns represent targets.

  • normalise (bool | None) – If True, return a z-score by comparing the metric value to an ensemble of directed random graphs with the same number of nodes and links (G(n,m)). If False or None, the metric is computed without normalisation (default).

  • n_random (int) – Number of random realisations for the null ensemble. Only valid when normalise=True. Default is 20.

  • random_seed (int | None) – Random seed for reproducibility of the null ensemble. Only valid when normalise=True.

Returns:

Number of nodes with no outbound connections, or the corresponding z-score if normalise=True.

Return type:

int | float

Raises:

  • ValueError – If weight_matrix is not square.

  • ValueError – If normalise is False or None and normalisation parameters (n_random or random_seed) are provided.

  • ValueError – If normalise=True and weight_matrix is not strictly binary (values must be in {0,1}). Weighted normalisation is not supported.

  • ValueError – If normalise=True and the diagonal of weight_matrix is not zero (no self-loops are assumed).

Normalisation details:

  • The null model is a directed Erdos–Rényi G(n,m) ensemble with the same number of nodes and links as the input network, sampled using igraph.Graph.Erdos_Renyi() with directed=True and loops=False.

  • The returned value is a z-score: z = (x_true − μ_null) / σ_null.

  • If σ_null = 0 at any position, the returned z-score at that position is NaN.

Example:#

>>> import numpy as np
>>> from delaynet.network_analysis.metrics import isolated_nodes_outbound
>>> # Example adjacency matrix
>>> weights = np.array([[0, 1, 0], [0, 0, 1], [0, 0, 0]])
>>> count = isolated_nodes_outbound(weights)
>>> isinstance(count, int)
True

Compute the link density of the network.

Link density is the ratio of existing connections to the maximum possible number of connections in the network. This is equivalent to network density.

Parameters:

  • weight_matrix (numpy.ndarray, shape (n_nodes, n_nodes)) – Matrix of connection weights. Non-zero values indicate connections.

  • directed (bool) – If True, treat the network as directed.

  • normalise (bool | None) – If True, return a z-score by comparing the metric value to an ensemble of directed random graphs with the same number of nodes and links (G(n,m)). If False or None, the metric is computed without normalisation (default).

  • n_random (int) – Number of random realisations for the null ensemble. Only valid when normalise=True. Default is 20.

  • random_seed (int | None) – Random seed for reproducibility of the null ensemble. Only valid when normalise=True.

Returns:

Link density value between 0 and 1, or the corresponding z-score if normalise=True.

Return type:

float

Raises:

  • ValueError – If weight_matrix is not square.

  • ValueError – If normalise is False or None and normalisation parameters (n_random or random_seed) are provided.

  • ValueError – If normalise=True and weight_matrix is not strictly binary (values must be in {0,1}). Weighted normalisation is not supported.

  • ValueError – If normalise=True and the diagonal of weight_matrix is not zero (no self-loops are assumed).

Normalisation details:

  • The null model is a directed Erdos–Rényi G(n,m) ensemble with the same number of nodes and links as the input network, sampled using igraph.Graph.Erdos_Renyi() with directed=True and loops=False.

  • The returned value is a z-score: z = (x_true − μ_null) / σ_null. For vector-valued metrics, the z-score is computed element-wise.

  • If σ_null = 0 at any position, the returned z-score at that position is NaN.

Example:#

>>> import numpy as np
>>> from delaynet.network_analysis.metrics import link_density
>>> # Example binary adjacency matrix
>>> weights = np.array([[0, 1, 0], [1, 0, 1], [0, 1, 0]])
>>> density = link_density(weights)
>>> isinstance(density, float)
True
delaynet.network_analysis.metrics.reciprocity(weight_matrix: ndarray) → float[source]#

Compute the reciprocity of a directed network.

Reciprocity measures the tendency of vertex pairs to form mutual connections. It is defined as the fraction of edges that are reciprocated in a directed network. Formally, the reciprocity is calculated as:

\[R = \frac{1}{m} \sum_{i,j} A_{i,j} A_{j,i} = \frac{1}{m} \mathrm{Tr} \, A^2\]

where \(m\) is the number of edges and \(A\) is the adjacency matrix of the graph. Note that \(A_{i,j} A_{j,i} = 1\) if and only if \(i\) links to \(j\) and vice versa.

This implementation uses igraph’s Graph.reciprocity() method.

For undirected networks, reciprocity is not defined and this function will raise a ValueError.

Parameters:

  • weight_matrix (numpy.ndarray, shape (n_nodes, n_nodes)) – Matrix of connection weights. Non-zero values indicate connections.

  • normalise (bool | None) – If True, return a z-score by comparing the metric value to an ensemble of directed random graphs with the same number of nodes and links (G(n,m)). If False or None, the metric is computed without normalisation (default).

  • n_random (int) – Number of random realisations for the null ensemble. Only valid when normalise=True. Default is 20.

  • random_seed (int | None) – Random seed for reproducibility of the null ensemble. Only valid when normalise=True.

Returns:

Reciprocity value between 0 and 1, or the corresponding z-score if normalise=True.

Return type:

float

Raises:

  • ValueError – If weight_matrix is not square or if the network is undirected.

  • ValueError – If normalise is False or None and normalisation parameters (n_random or random_seed) are provided.

  • ValueError – If normalise=True and weight_matrix is not strictly binary (values must be in {0,1}). Weighted normalisation is not supported.

  • ValueError – If normalise=True and the diagonal of weight_matrix is not zero (no self-loops are assumed).

Normalisation details:

  • The null model is a directed Erdos–Rényi G(n,m) ensemble with the same number of nodes and links as the input network, sampled using igraph.Graph.Erdos_Renyi() with directed=True and loops=False.

  • The returned value is a z-score: z = (x_true − μ_null) / σ_null.

  • If σ_null = 0 at any position, the returned z-score at that position is NaN.

Example:#

>>> import numpy as np
>>> from delaynet.network_analysis.metrics import reciprocity
>>> # Example directed adjacency matrix
>>> weights = np.array([[0, 1, 0], [0, 0, 1], [1, 0, 0]])
>>> recip = reciprocity(weights)
>>> isinstance(recip, float)
True

References:#

delaynet.network_analysis.metrics.transitivity(weight_matrix: ndarray) → float[source]#

Compute the transitivity (global clustering coefficient) of the network.

Transitivity measures the fraction of all possible triangles present in the graph. Following the NetworkX definition, transitivity is calculated as:

\[T = 3 \frac{\text{number of triangles}}{\text{number of triads}}\]

where triads are sets of 3 nodes with at least 2 edges between them.

This implementation uses igraph’s Graph.transitivity_undirected() method, which correctly implements the above definition. For directed graphs, the network is first converted to undirected before calculation.

Note that for directed networks, the direction of edges is ignored when calculating transitivity, as the concept of triangles is defined for undirected graphs. For directed networks, consider using reciprocity() to measure the tendency of vertex pairs to form mutual connections.

Due to the way NetworkX handles directed networks when calculating transitivity, transitivity calculated with this method differs on undirected graphs. This implementation collapses the directed network into an undirected network and calculates transitivity using igraph’s method.

Parameters:

  • weight_matrix (numpy.ndarray, shape (n_nodes, n_nodes)) – Matrix of connection weights. Non-zero values indicate connections.

  • normalise (bool | None) – If True, return a z-score by comparing the metric value to an ensemble of directed random graphs with the same number of nodes and links (G(n,m)). If False or None, the metric is computed without normalisation (default).

  • n_random (int) – Number of random realisations for the null ensemble. Only valid when normalise=True. Default is 20.

  • random_seed (int | None) – Random seed for reproducibility of the null ensemble. Only valid when normalise=True.

Returns:

Transitivity value between 0 and 1, or the corresponding z-score if normalise=True.

Return type:

float

Raises:

  • ValueError – If weight_matrix is not square.

  • ValueError – If normalise is False or None and normalisation parameters (n_random or random_seed) are provided.

  • ValueError – If normalise=True and weight_matrix is not strictly binary (values must be in {0,1}). Weighted normalisation is not supported.

  • ValueError – If normalise=True and the diagonal of weight_matrix is not zero (no self-loops are assumed).

Normalisation details:

  • The null model is a directed Erdos–Rényi G(n,m) ensemble with the same number of nodes and links as the input network, sampled using igraph.Graph.Erdos_Renyi() with directed=True and loops=False.

  • The returned value is a z-score: z = (x_true − μ_null) / σ_null.

  • If σ_null = 0 at any position, the returned z-score at that position is NaN.

Example:#

>>> import numpy as np
>>> from delaynet.network_analysis.metrics import transitivity
>>> # Example binary adjacency matrix
>>> weights = np.array([[0, 1, 1], [1, 0, 1], [1, 1, 0]])
>>> trans = transitivity(weights)
>>> isinstance(trans, float)
True

delaynet.network_analysis.pruning module#

Network pruning methods for delaynet.

This module provides methods for pruning networks by removing weak or statistically insignificant connections from reconstructed networks.

delaynet.network_analysis.pruning.statistical_pruning(p_values: ndarray, alpha: float = 0.05, correction: str | None = None, **multipletests_kwargs: Any) → ndarray[source]#

Prune network connections by statistical significance, with an optional multiple‐comparison correction.

Parameters:

  • p_values (numpy.ndarray) – Matrix of p-values, shape (n_nodes, n_nodes).

  • alpha (float) – Per-test significance level (default 0.05).

  • correction (str or None) – Name of the correction method to use. Must be one of the methods supported by statsmodels.stats.multitest.multipletests() (e.g. ‘bonferroni’, ‘sidak’, ‘holm’, ‘fdr_bh’, ‘fdr_by’, ‘fdr_tsbh’, etc.). If None, no correction is applied.

  • multipletests_kwargs (dict) – Additional keyword arguments to pass to multipletests(), such as maxiter, is_sorted, returnsorted.

Returns:

Boolean mask indicating which connections are significant after (optional) correction.

Return type:

numpy.ndarray

Example:#

>>> mask = statistical_pruning(p_values,
...                            alpha=0.05,
...                            correction='fdr_bh',
...                            maxiter=2)

Module contents#

Network analysis module for delaynet.

This module provides functionality for network pruning and computing basic network metrics from reconstructed networks.