API Reference

This page provides detailed API documentation for the Cohomological Risk Scoring package.

PCRScorer

class cohomological_risk_scoring.PCRScorer(max_dim: int = 2, filtration_param: str = 'weight')[source]

Bases: object

Main class for computing Persistence of Cohomological Risk scores.

__init__(max_dim: int = 2, filtration_param: str = 'weight')[source]

Initialize PCR scorer.

Parameters:

max_dim (int, default=2) – Maximum simplex dimension
filtration_param (str, default='weight') – Parameter for filtration (‘weight’, ‘time’, ‘amount’)

compute_all_scores(persistence_weight: float = 1.0, norm_weight: float = 0.5) → Dict[source]

Compute PCR scores for all vertices.

Parameters:

persistence_weight (float, default=1.0) – Weight for persistence term
norm_weight (float, default=0.5) – Weight for cocycle norm term

Returns:

Dictionary mapping vertex IDs to PCR scores

Return type:

Dict

fit(graph: Graph, vertex_features: Dict, edge_features: Dict, restriction_func: Callable | None = None)[source]

Fit the model to financial data.

Parameters:

graph (nx.Graph) – Financial transaction graph
vertex_features (Dict) – Vertex feature vectors
edge_features (Dict) – Edge feature values
restriction_func (Callable, optional) – Restriction function for sheaf

generate_report() → str[source]

Generate analysis report.

Returns:: Formatted analysis report
Return type:: str

get_risk_classes(threshold: float = 0.1) → List[Dict][source]

Get identified risk classes.

Parameters:: threshold (float, default=0.1) – Minimum persistence threshold
Returns:: List of risk class dictionaries
Return type:: List[Dict]

visualize_persistence(save_path: str | None = None)[source]

Visualize persistence diagram and PCR scores.

Parameters:: save_path (str, optional) – Path to save the figure

FinancialSheaf

class cohomological_risk_scoring.FinancialSheaf(max_simplex_dim: int = 2)[source]

Bases: object

Implements the financial sheaf model for cohomological risk scoring.

__init__(max_simplex_dim: int = 2)[source]

Initialize the financial sheaf.

Parameters:: max_simplex_dim (int, default=2) – Maximum dimension of simplices to consider (2 for triangles, 3 for tetrahedra, etc.)

build_complex_from_graph(graph: Graph, threshold: float = 0.0) → Dict[int, List][source]

Build simplicial complex from financial graph using clique expansion.

Parameters:

graph (nx.Graph) – Financial transaction graph with nodes as entities and edges as transactions
threshold (float, default=0.0) – Minimum edge weight to include in the complex

Returns:

Dictionary mapping dimension to list of simplices

Return type:

Dict[int, List]

compute_coboundary_matrix(dim: int) → csr_matrix[source]

Compute coboundary matrix δ^p: C^p → C^{p+1}.

Parameters:: dim (int) – Dimension p for cochains
Returns:: Coboundary matrix
Return type:: sparse.csr_matrix

compute_cohomology(dim: int) → Dict[source]

Compute cohomology group H^p for given dimension.

Parameters:: dim (int) – Dimension p
Returns:: Dictionary with basis of H^p, cocycles, and coboundaries
Return type:: Dict

compute_pcr_score(vertex: int, persistence_weight: float = 1.0, norm_weight: float = 0.5) → float[source]

Compute PCR score for a vertex.

Parameters:

vertex (int) – Vertex ID
persistence_weight (float, default=1.0) – Weight for persistence term
norm_weight (float, default=0.5) – Weight for cocycle norm term

Returns:

PCR score

Return type:

float

compute_persistent_cohomology(filtration_param: str = 'weight', max_filtration: float | None = None) → Dict[source]

Compute persistent cohomology across filtration.

Parameters:

filtration_param (str, default='weight') – Parameter to use for filtration (‘weight’, ‘time’, ‘amount’)
max_filtration (float, optional) – Maximum filtration value

Returns:

Dictionary with persistence diagrams and intervals

Return type:

Dict

define_sheaf_data(vertex_features: Dict, edge_features: Dict, restriction_func: Callable | None = None)[source]

Define sheaf data with vertex and edge stalks and restriction maps.

Parameters:

vertex_features (Dict) – Dictionary mapping vertex IDs to feature vectors
edge_features (Dict) – Dictionary mapping edge tuples (u, v) to feature values
restriction_func (Callable, optional) – Function defining restriction maps ρ: F(v) → F(e) Default: projection to first component

get_risk_classes(threshold: float = 0.1) → List[Dict][source]

Identify Cohomological Risk Classes (CRCs) above threshold.

Parameters:: threshold (float, default=0.1) – Minimum persistence threshold
Returns:: List of CRC dictionaries
Return type:: List[Dict]

Utility Functions

Helper functions for creating example networks and data preprocessing.

Author: Idriss Bado

cohomological_risk_scoring.utils.compute_network_statistics(G: Graph) → Dict[source]

Compute basic network statistics.

Parameters:: G (nx.Graph) – Input graph
Returns:: Dictionary of network statistics
Return type:: Dict

cohomological_risk_scoring.utils.create_example_financial_network(n_vertices: int = 20) → Tuple[Graph, Dict, Dict][source]

Legacy function name for backward compatibility.

Parameters:: n_vertices (int, default=20) – Number of vertices in the network
Returns:: Graph, vertex features, and edge features
Return type:: Tuple[nx.Graph, Dict, Dict]

cohomological_risk_scoring.utils.create_example_network(n_vertices: int = 20, edge_probability: float = 0.3, seed: int | None = None) → Tuple[Graph, Dict, Dict][source]

Create an example financial network for testing and demonstration.

Parameters:

n_vertices (int, default=20) – Number of vertices (entities) in the network
edge_probability (float, default=0.3) – Probability of edge creation in Erdős-Rényi model
seed (int, optional) – Random seed for reproducibility

Returns:

Graph, vertex features, and edge features

Return type:

Tuple[nx.Graph, Dict, Dict]

cohomological_risk_scoring.utils.load_transaction_data(filepath: str) → Tuple[Graph, Dict, Dict][source]

Load financial transaction data from file.

Parameters:: filepath (str) – Path to the data file
Returns:: Graph, vertex features, and edge features
Return type:: Tuple[nx.Graph, Dict, Dict]

Notes

Expected file format: CSV with columns: source, target, amount, timestamp

cohomological_risk_scoring.utils.normalize_features(features: Dict, method: str = 'standard') → Dict[source]

Normalize feature vectors.

Parameters:

features (Dict) – Dictionary of feature vectors
method (str, default='standard') – Normalization method: ‘standard’, ‘minmax’, or ‘l2’

Returns:

Normalized features

Return type:

Dict