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.

Returns:

Array of betweenness centrality values for each node.

Return type:

numpy.ndarray, shape (n_nodes,)

Raises:

ValueError – If weight_matrix is not square.

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.

Returns:

Array of eigenvector centrality values for each node.

Return type:

numpy.ndarray, shape (n_nodes,)

Raises:

ValueError – If weight_matrix is not square.

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.

Returns:

Global efficiency value between 0 and 1.

Return type:

float

Raises:

ValueError – If weight_matrix is not square.

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.

Returns:

Number of nodes with no inbound connections.

Return type:

int

Raises:

ValueError – If weight_matrix is not square.

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.

Returns:

Number of nodes with no outbound connections.

Return type:

int

Raises:

ValueError – If weight_matrix is not square.

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.

Returns:

Link density value between 0 and 1.

Return type:

float

Raises:

ValueError – If weight_matrix is not square.

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.

Returns:

Reciprocity value between 0 and 1.

Return type:

float

Raises:

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

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.

Returns:

Transitivity value between 0 and 1.

Return type:

float

Raises:

ValueError – If weight_matrix is not square.

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.

Contents