qbiocode.apps.quvine.evaluation.classification module

Node Classification Evaluation Module

This module provides functions for evaluating node embeddings on node classification tasks. Includes multiple label generation strategies and comprehensive evaluation metrics.

Label Generation Strategies: 1. Community-based: Louvain, Label Propagation, Spectral Clustering 2. Degree-based: Structural role binning 3. Centrality-based: Betweenness, Closeness, Eigenvector, PageRank 4. Core-periphery: K-core decomposition, Rich-club 5. Homophily-based: Graph structure-aware labels (from Q-Caliber)

Evaluation Metrics: - Accuracy, Precision, Recall, F1-score (macro/micro/weighted) - Confusion matrix - Per-class metrics

Summary

Functions:

evaluate_all_label_strategies	Evaluate embeddings using all label generation strategies plus an ensemble.
evaluate_nc_stratified	Evaluate node classification stratified by node degree and distance from hubs.
evaluate_node_classification	Evaluate node embeddings on classification task.
flatten_classification_results	Flatten results from evaluate_all_label_strategies into one dict per strategy.
generate_centrality_labels	Generate node labels based on centrality measures.
generate_community_labels	Generate node labels based on community detection.
generate_core_periphery_labels	Generate node labels based on core-periphery structure.
generate_degree_labels	Generate node labels based on degree binning.
generate_homophily_labels	Generate node labels with homophily (graph structure influence).
summarize_classification_results	Summarize classification results across all label strategies.

Reference

generate_community_labels(G, method='louvain', min_community_size=5, resolution=1.0)

Generate node labels based on community detection.

Parameters:

• G (Graph) – NetworkX graph

• method (str) – Community detection method (‘louvain’, ‘label_propagation’, ‘spectral’)

• min_community_size (int) – Minimum nodes per community (smaller communities merged)

• resolution (float) – Resolution parameter for Louvain (higher = more communities)

Return type:

Dict[int, int]

Returns:

Dictionary mapping node IDs to community labels

generate_degree_labels(G, n_bins=5, method='quantile')

Generate node labels based on degree binning.

Parameters:

• G (Graph) – NetworkX graph

• n_bins (int) – Number of degree bins

• method (str) – Binning method (‘quantile’ or ‘uniform’)

Return type:

Dict[int, int]

Returns:

Dictionary mapping node IDs to degree-based labels

generate_centrality_labels(G, centrality_type='betweenness', n_bins=5)

Generate node labels based on centrality measures.

Parameters:

• G (Graph) – NetworkX graph

• centrality_type (str) – Type of centrality (‘betweenness’, ‘closeness’, ‘eigenvector’, ‘pagerank’)

• n_bins (int) – Number of centrality bins

Return type:

Dict[int, int]

Returns:

Dictionary mapping node IDs to centrality-based labels

generate_core_periphery_labels(G, method='k_core', n_bins=3)

Generate node labels based on core-periphery structure.

Parameters:

• G (Graph) – NetworkX graph

• method (str) – Method (‘k_core’ or ‘rich_club’)

• n_bins (int) – Number of bins for rich-club method

Return type:

Dict[int, int]

Returns:

Dictionary mapping node IDs to core-periphery labels

generate_homophily_labels(G, embeddings=None, feature_weight=0.5, neighbor_weight=0.5, noise_std=0.15, n_bins=2, seed_nodes=None, random_state=42)

Generate node labels with homophily (graph structure influence).

This strategy creates labels that respect graph structure without direct data leakage. It combines feature-based scores with neighbor influence to create realistic labels where similar/connected nodes tend to have similar labels.

Strategy (from Q-Caliber notebook): 1. Create feature-based scores from embeddings or random features 2. Initialize labels based on feature scores 3. Add homophily: neighbors of positive nodes more likely positive 4. Combine feature scores (50%) with neighbor influence (50%) 5. Add noise and create final labels

Parameters:

• G (Graph) – NetworkX graph

• embeddings (Optional[ndarray]) – Node embeddings (optional, if None uses random features)

• feature_weight (float) – Weight for feature-based scores (default 0.5)

• neighbor_weight (float) – Weight for neighbor influence (default 0.5)

• noise_std (float) – Standard deviation of noise to add (default 0.15)

• n_bins (int) – Number of label classes (default 2 for binary)

• seed_nodes (Optional[List[int]]) – Optional list of nodes to force as positive class

• random_state (int) – Random seed

Return type:

Dict[int, int]

Returns:

Dictionary mapping node IDs to homophily-based labels

evaluate_node_classification(embeddings, labels, node_list, test_size=0.3, classifier='logistic', n_splits=5, random_state=42)

Evaluate node embeddings on classification task.

Parameters:

• embeddings (ndarray) – Node embedding matrix (n_nodes x embedding_dim)

• labels (Dict[int, int]) – Dictionary mapping node IDs to class labels

• node_list (List[int]) – List of node IDs corresponding to embedding rows

• test_size (float) – Fraction of data for testing

• classifier (str) – Classifier type (‘logistic’ or ‘random_forest’)

• n_splits (int) – Number of cross-validation splits

• random_state (int) – Random seed

Return type:

Dict[str, float]

Returns:

Dictionary of evaluation metrics

evaluate_all_label_strategies(G, embeddings, node_list, test_size=0.3, random_state=42, pregenerated_split=None)

Evaluate embeddings using all label generation strategies plus an ensemble.

Strategies (8 total):

1. community_louvain

2. community_label_propagation

3. degree_based

4. centrality_betweenness

5. centrality_pagerank

6. core_periphery

7. homophily_based

8. ensemble (majority-vote across all successful strategies above)

Parameters:

• G (Graph) – NetworkX graph

• embeddings (ndarray) – Node embedding matrix

• node_list (List[int]) – List of node IDs

• test_size (float) – Test set fraction

• random_state (int) – Random seed

• pregenerated_split – Accepted for API compatibility; unused here.

Return type:

Dict[str, Dict[str, float]]

Returns:

Dictionary mapping strategy names to evaluation results

evaluate_nc_stratified(G, embeddings, node_list, label_strategy='louvain', n_degree_bins=5, dist_max_bin=5, test_size=0.3, random_state=42)

Evaluate node classification stratified by node degree and distance from hubs.

Produces one row per (bin_type, bin_label) for the primary label strategy, reporting per-bin accuracy on the test nodes. This mirrors the degree/ distance-matched controls used in LP and ranking evaluations.

Parameters:

• G (nx.Graph)

• embeddings (np.ndarray (n_nodes × dim))

• node_list (list) – Nodes in the same order as rows of embeddings.

• label_strategy (str) – Community detection method to generate labels (‘louvain’ or ‘label_propagation’).

• n_degree_bins (int) – Number of degree quantile bins (default 5 → Q1–Q5).

• dist_max_bin (int) – Distances ≥ this value are grouped into a single “{dist_max_bin}+” bin.

• test_size (float) – Fraction of nodes held out for evaluation.

• random_state (int)

Returns:

Each dict has keys: bin_type, bin_label, bin_n_nodes, accuracy, f1_macro. method and network_id are added by the caller.

Return type:

list of dicts

flatten_classification_results(results, network_id, method)

Flatten results from evaluate_all_label_strategies into one dict per strategy.

Returns one row per label strategy with columns: network_id, method, label_strategy, f1_macro, accuracy, precision_macro, recall_macro, n_classes, n_train, n_test. Failed strategies produce NaN values so the schema is always consistent.

Return type:

List[Dict]

summarize_classification_results(results)

Summarize classification results across all label strategies.

Parameters:

results (Dict[str, Dict[str, float]]) – Dictionary of results from evaluate_all_label_strategies

Return type:

Dict[str, float]

Returns:

Dictionary of summary statistics