Network Construction¶

Network builder for financial network analysis.

This module provides the FinancialNetworkBuilder class for constructing financial networks from preprocessed data.

class scr_financial.network.builder.FinancialNetworkBuilder(preprocessor)[source]¶

Bases: object

Constructs financial networks from preprocessed data.

Parameters:: preprocessor (DataPreprocessor) – Preprocessor containing the data to build the network from

G¶

NetworkX graph representing the financial network

Type:: networkx.Graph

adjacency_matrix¶

Sparse adjacency matrix of the network

Type:: scipy.sparse.csr_matrix

laplacian¶

Graph Laplacian matrix

Type:: scipy.sparse.csr_matrix

eigenvalues¶

Eigenvalues of the Laplacian

Type:: numpy.ndarray

eigenvectors¶

Eigenvectors of the Laplacian

Type:: numpy.ndarray

__init__(preprocessor)[source]¶

Initialize the network builder with preprocessed data.

Parameters:: preprocessor (DataPreprocessor)

construct_network(time_point, edge_weight_type='interbank_exposures')[source]¶

Construct network for a specific time point.

Parameters:

time_point (str or pd.Timestamp) – Date for which to construct the network
edge_weight_type (str, optional) – Type of edge weight to use, by default ‘interbank_exposures’

Returns:

Constructed financial network

Return type:

networkx.Graph

compute_laplacian(normalized=True)[source]¶

Compute the graph Laplacian.

Parameters:: normalized (bool, optional) – Whether to compute the normalized Laplacian, by default True
Returns:: Graph Laplacian matrix
Return type:: scipy.sparse.csr_matrix

spectral_analysis()[source]¶

Perform spectral analysis of the Laplacian.

Returns:: Tuple containing eigenvalues and eigenvectors
Return type:: tuple

find_spectral_gap()[source]¶

Identify the spectral gap for coarse-graining.

Returns:: Tuple containing the index of the gap and the gap size
Return type:: tuple

get_node_attribute_matrix(attribute)[source]¶

Get matrix of node attributes.

Parameters:: attribute (str) – Node attribute to extract
Returns:: Matrix of node attributes
Return type:: numpy.ndarray

get_edge_weight_matrix()[source]¶

Get matrix of edge weights.

Returns:: Matrix of edge weights
Return type:: numpy.ndarray

compute_centrality_measures()[source]¶

Compute various centrality measures for the network.

Returns:: Dictionary mapping centrality types to dictionaries of node centralities
Return type:: dict

compute_community_structure(method='louvain')[source]¶

Compute community structure of the network.

Parameters:: method (str, optional) – Community detection method, by default ‘louvain’
Returns:: Dictionary mapping nodes to community IDs
Return type:: dict

Spectral coarse-graining for financial networks.

This module implements spectral coarse-graining techniques for simplifying financial networks while preserving their essential structural and dynamic properties.

class scr_financial.network.coarse_graining.SpectralCoarseGraining(network_builder)[source]¶

Bases: object

Implements spectral coarse-graining for financial networks.

Parameters:: network_builder (FinancialNetworkBuilder)

coarse_grained_laplacian¶: Coarse-grained Laplacian matrix.

coarse_grained_adjacency¶: Coarse-grained adjacency matrix.

rescaled_adjacency¶: Rescaled coarse-grained adjacency matrix.

clusters¶: Cluster assignments for nodes.

__init__(network_builder)[source]¶

Initialize the coarse-graining with a network builder.

Parameters:: network_builder (FinancialNetworkBuilder) – Network builder containing the network to coarse-grain.
Return type:: None

classmethod from_adjacency(adj_matrix, node_ids)[source]¶

Create an SCG instance directly from an adjacency matrix (no DataPreprocessor needed).

Parameters:

adj_matrix (ndarray)
node_ids (List[str])

Return type:

SpectralCoarseGraining

coarse_grain(k=None)[source]¶

Perform spectral coarse-graining using k eigenmodes.

Parameters:: k (int | None) – Number of eigenmodes to use. If None, determined automatically using spectral gap.
Returns:: Coarse-grained Laplacian matrix as an ndarray.
Return type:: ndarray

contract_vertices()[source]¶

Vertex contraction: merge nodes with negative off-diagonal in A₁.

Nodes that are “similar” at the coarse scale (negative off-diagonal entries in the coarse-grained adjacency) are merged into super-nodes with summed edge weights.

Returns:: Contracted adjacency matrix (may be smaller than original).
Return type:: ndarray

rescale(lambda_k=None)[source]¶

Rescale the coarse-grained adjacency matrix.

Parameters:: lambda_k (float | None) – Eigenvalue to use for rescaling. If None, uses the k-th eigenvalue where k is from find_spectral_gap.
Returns:: Rescaled coarse-grained adjacency matrix.
Raises:: ValueError – If coarse-grained adjacency has not been computed.
Return type:: ndarray

identify_clusters(n_clusters=None)[source]¶

Identify clusters based on eigenvectors.

Parameters:: n_clusters (int | None) – Number of clusters. If None, determined from spectral gap.
Returns:: Cluster assignments for nodes.
Return type:: ndarray

create_coarse_grained_graph()[source]¶

Create a coarse-grained graph based on identified clusters.

Returns:: Coarse-grained graph.
Return type:: Graph

map_node_to_cluster(node)[source]¶

Map an original node to its cluster.

Parameters:: node (str) – Original node identifier.
Returns:: Cluster identifier.
Raises:: ValueError – If clusters have not been identified or node is not found.
Return type:: str

compute_coarse_graining_error()[source]¶

Compute the error introduced by coarse-graining.

Returns:: Relative error in eigenvalues.
Raises:: ValueError – If coarse-grained Laplacian has not been computed.
Return type:: float

compute_reconstruction_accuracy(time_steps=15)[source]¶

Measure how well the CG Laplacian reconstructs the original diffusion signal.

For each time step t, computes: - correlation between p_orig(t) and p_cg(t) - RMSE - R² (coefficient of determination)

Returns dict with keys: ‘time’, ‘correlation’, ‘rmse’, ‘r2’.

Parameters:: time_steps (int)
Return type:: Dict[str, List[float]]

compare_diffusion_dynamics(time_steps=10)[source]¶

Compare diffusion dynamics between original and coarse-grained networks.

Uses the matrix exponential (scipy.linalg.expm) to compute the exact diffusion operator e^{-tL}, avoiding element-wise exp.

Parameters:: time_steps (int) – Number of time steps to simulate. Defaults to 10.
Returns:: List of relative errors at each time step.
Raises:: ValueError – If coarse-grained Laplacian has not been computed.
Return type:: List[float]