qbiocode.apps.quvine.reproducibility.method_adapters module

Method Adapters for Reproducible Benchmarking Pipeline

This module provides adapter functions that wrap all 42 QuVINE methods to work with the reproducible pipeline interface.

Each adapter: 1. Accepts pre-generated graph and split 2. Uses the provided canonical seed 3. Returns standardized metrics 4. Does NOT modify input data or create its own splits

Summary

Functions:

evaluate_link_prediction	Evaluate link prediction using dot product similarity.
evaluate_node_ranking	Evaluate node ranking task.
generate_quantum_targets_from_walks	Generate quantum walk targets for filter calibration.
get_method_adapter	Get the adapter function for a method.
run_appnp_adapter	Adapter for APPNP method.
run_baseline_filter_adapter	Adapter for generic baseline filter (defaults to heat kernel).
run_baseline_filter_heat_adapter	Adapter for baseline heat kernel filter (no quantum calibration).
run_baseline_filter_poly_adapter	Adapter for baseline polynomial filter (no quantum calibration).
run_baseline_gcnmf_adapter	Adapter for baseline GCN-MF (no quantum calibration).
run_ctqw_fusion_adapter	Fusion method combining CTQW-based embeddings.
run_dtqw_fusion_adapter	Fusion method combining DTQW-based embeddings.
run_filter_ctqw_heat_adapter	Adapter for CTQW + heat kernel filter.
run_filter_ctqw_poly_adapter	Adapter for CTQW + polynomial filter.
run_filter_rwr_heat_adapter	Adapter for RWR + heat kernel filter.
run_filter_rwr_poly_adapter	Adapter for RWR + polynomial filter.
run_gat_adapter	Generic GAT adapter that handles all 12 GAT variants.
run_gat_baseline_adapter	GAT with raw structural features.
run_gat_ctqw_adapter	GAT with direct CTQW features.
run_gat_ctqw_heat_adapter	GAT with CTQW-calibrated heat kernel features.
run_gat_ctqw_poly_adapter	GAT with CTQW-calibrated polynomial features.
run_gat_dtqw_adapter	GAT with direct DTQW features.
run_gat_dtqw_heat_adapter	GAT with DTQW-calibrated heat kernel features.
run_gat_dtqw_poly_adapter	GAT with DTQW-calibrated polynomial features.
run_gat_heat_adapter	GAT with fixed heat kernel features.
run_gat_poly_adapter	GAT with fixed polynomial features.
run_gat_rwr_adapter	GAT with RWR walk features.
run_gat_rwr_heat_adapter	GAT with RWR-calibrated heat kernel features.
run_gat_rwr_poly_adapter	GAT with RWR-calibrated polynomial features.
run_graphgps_adapter	Generic GraphGPS adapter that handles all 12 GraphGPS variants.
run_graphgps_baseline_adapter	GraphGPS with raw structural features.
run_graphgps_ctqw_adapter	GraphGPS with direct CTQW features.
run_graphgps_ctqw_heat_adapter	GraphGPS with CTQW-calibrated heat kernel features.
run_graphgps_ctqw_poly_adapter	GraphGPS with CTQW-calibrated polynomial features.
run_graphgps_dtqw_adapter	GraphGPS with direct DTQW features.
run_graphgps_dtqw_heat_adapter	GraphGPS with DTQW-calibrated heat kernel features.
run_graphgps_dtqw_poly_adapter	GraphGPS with DTQW-calibrated polynomial features.
run_graphgps_heat_adapter	GraphGPS with fixed heat kernel features.
run_graphgps_poly_adapter	GraphGPS with fixed polynomial features.
run_graphgps_rwr_adapter	GraphGPS with RWR walk features.
run_graphgps_rwr_heat_adapter	GraphGPS with RWR-calibrated heat kernel features.
run_graphgps_rwr_poly_adapter	GraphGPS with RWR-calibrated polynomial features.
run_graphsage_adapter	Adapter for GraphSAGE method.
run_netmf_adapter	Adapter for NetMF method.
run_node2vec_adapter	Adapter for Node2Vec method.
run_quvine_ctqw_adapter	Adapter for QuVINE CTQW (Continuous-Time Quantum Walk + SGNS).
run_quvine_dtqw_adapter	Adapter for QuVINE DTQW (Discrete-Time Quantum Walk + SGNS).
run_quvine_rwr_adapter	Adapter for QuVINE RWR (Random Walk with Restart + SGNS).
run_quvine_sgns	Run QuVINE SGNS embedding with specified walk type.
run_rwr_fusion_adapter	Fusion method combining RWR-based embeddings.
train_classifier	Train a logistic regression classifier on embeddings.

Reference

train_classifier(embeddings, train_idx, val_idx, test_idx, labels, seed)

Train a logistic regression classifier on embeddings.

Parameters:

• embeddings (np.ndarray) – Node embeddings [N, d]

• train_idx (np.ndarray) – Training indices

• val_idx (np.ndarray) – Validation indices

• test_idx (np.ndarray) – Test indices

• labels (np.ndarray) – Node labels

• seed (int) – Random seed

Returns:

Classification metrics

Return type:

dict

evaluate_link_prediction(embeddings, test_edges, neg_test_edges)

Evaluate link prediction using dot product similarity.

Parameters:

• embeddings (np.ndarray) – Node embeddings [N, d]

• test_edges (list) – Positive test edges

• neg_test_edges (list) – Negative test edges

Returns:

Link prediction metrics: auc_roc, auc_pr, f1.

Return type:

dict

Notes

Ranking metrics are undefined unless both classes are present. When either test_edges or neg_test_edges is empty the three metrics are returned as nan – not as 0.5 – because 0.5 is an achievable score and reporting it would make an undefined evaluation indistinguishable from a genuinely chance-level one, and would drag any average over methods toward chance. Aggregate these with np.nanmean.

Raises:

ValueError – If both edge lists are empty, or if an edge references a node index outside embeddings.

evaluate_node_ranking(embeddings, seed_nodes, target_nodes, k_values=[10, 20, 50])

Evaluate node ranking task.

Parameters:

• embeddings (np.ndarray) – Node embeddings [N, d]

• seed_nodes (list) – Seed node indices

• target_nodes (list) – Target node indices

• k_values (list) – K values for precision@k

Returns:

Ranking metrics

Return type:

dict

run_node2vec_adapter(G, split, task, config=None, seed=42)

Adapter for Node2Vec method.

Return type:

Dict[str, float]

run_netmf_adapter(G, split, task, config=None, seed=42)

Adapter for NetMF method.

Return type:

Dict[str, float]

run_graphsage_adapter(G, split, task, config=None, seed=42)

Adapter for GraphSAGE method.

Return type:

Dict[str, float]

run_appnp_adapter(G, split, task, config=None, seed=42)

Adapter for APPNP method.

Return type:

Dict[str, float]

run_quvine_sgns(G, walk_type, config=None, seed=42)

Run QuVINE SGNS embedding with specified walk type.

Parameters:

• G (nx.Graph) – Input graph

• walk_type (str) – Type of walk: ‘rwr’, ‘ctqw’, or ‘dtqw’

• config (dict, optional) – Configuration parameters

• seed (int) – Random seed

Returns:

Node embeddings (n_nodes x embedding_dim)

Return type:

np.ndarray

run_quvine_rwr_adapter(G, split, task, config=None, seed=42)

Adapter for QuVINE RWR (Random Walk with Restart + SGNS).

Return type:

Dict[str, float]

run_quvine_ctqw_adapter(G, split, task, config=None, seed=42)

Adapter for QuVINE CTQW (Continuous-Time Quantum Walk + SGNS).

Return type:

Dict[str, float]

run_quvine_dtqw_adapter(G, split, task, config=None, seed=42)

Adapter for QuVINE DTQW (Discrete-Time Quantum Walk + SGNS).

Return type:

Dict[str, float]

run_baseline_filter_heat_adapter(G, split, task, config=None, seed=42)

Adapter for baseline heat kernel filter (no quantum calibration).

Return type:

Dict[str, float]

run_baseline_filter_poly_adapter(G, split, task, config=None, seed=42)

Adapter for baseline polynomial filter (no quantum calibration).

Return type:

Dict[str, float]

generate_quantum_targets_from_walks(G, walk_type, config, seed, n_samples=10)

Generate quantum walk targets for filter calibration.

Samples subnetworks and computes quantum walk distributions. Returns targets with integer node IDs (not strings).

Return type:

List[Dict]

run_filter_rwr_heat_adapter(G, split, task, config=None, seed=42)

Adapter for RWR + heat kernel filter.

Return type:

Dict[str, float]

run_filter_rwr_poly_adapter(G, split, task, config=None, seed=42)

Adapter for RWR + polynomial filter.

Return type:

Dict[str, float]

run_filter_ctqw_heat_adapter(G, split, task, config=None, seed=42)

Adapter for CTQW + heat kernel filter.

Return type:

Dict[str, float]

run_filter_ctqw_poly_adapter(G, split, task, config=None, seed=42)

Adapter for CTQW + polynomial filter.

Return type:

Dict[str, float]

run_gat_adapter(G, split, task, method_name, config=None, seed=42)

Generic GAT adapter that handles all 12 GAT variants.

GAT variants differ only in their input features: - gat_baseline: raw structural features - gat_heat/poly: fixed filter parameters - gat_rwr/ctqw/dtqw: walk-based features - gat_*_heat/poly: quantum-calibrated filters

Return type:

Dict[str, float]

run_gat_baseline_adapter(G, split, task, config=None, seed=42)

GAT with raw structural features.

run_gat_heat_adapter(G, split, task, config=None, seed=42)

GAT with fixed heat kernel features.

run_gat_poly_adapter(G, split, task, config=None, seed=42)

GAT with fixed polynomial features.

run_gat_rwr_adapter(G, split, task, config=None, seed=42)

GAT with RWR walk features.

run_gat_ctqw_adapter(G, split, task, config=None, seed=42)

GAT with direct CTQW features.

run_gat_dtqw_adapter(G, split, task, config=None, seed=42)

GAT with direct DTQW features.

run_gat_rwr_heat_adapter(G, split, task, config=None, seed=42)

GAT with RWR-calibrated heat kernel features.

run_gat_rwr_poly_adapter(G, split, task, config=None, seed=42)

GAT with RWR-calibrated polynomial features.

run_gat_ctqw_heat_adapter(G, split, task, config=None, seed=42)

GAT with CTQW-calibrated heat kernel features.

run_gat_ctqw_poly_adapter(G, split, task, config=None, seed=42)

GAT with CTQW-calibrated polynomial features.

run_gat_dtqw_heat_adapter(G, split, task, config=None, seed=42)

GAT with DTQW-calibrated heat kernel features.

run_gat_dtqw_poly_adapter(G, split, task, config=None, seed=42)

GAT with DTQW-calibrated polynomial features.

run_graphgps_adapter(G, split, task, method_name, config=None, seed=42)

Generic GraphGPS adapter that handles all 12 GraphGPS variants.

GraphGPS variants differ only in their input features (same as GAT): - graphgps_baseline: raw structural features - graphgps_heat/poly: fixed filter parameters - graphgps_rwr/ctqw/dtqw: walk-based features - graphgps_*_heat/poly: quantum-calibrated filters

Return type:

Dict[str, float]

run_graphgps_baseline_adapter(G, split, task, config=None, seed=42)

GraphGPS with raw structural features.

run_graphgps_heat_adapter(G, split, task, config=None, seed=42)

GraphGPS with fixed heat kernel features.

run_graphgps_poly_adapter(G, split, task, config=None, seed=42)

GraphGPS with fixed polynomial features.

run_graphgps_rwr_adapter(G, split, task, config=None, seed=42)

GraphGPS with RWR walk features.

run_graphgps_ctqw_adapter(G, split, task, config=None, seed=42)

GraphGPS with direct CTQW features.

run_graphgps_dtqw_adapter(G, split, task, config=None, seed=42)

GraphGPS with direct DTQW features.

run_graphgps_rwr_heat_adapter(G, split, task, config=None, seed=42)

GraphGPS with RWR-calibrated heat kernel features.

run_graphgps_rwr_poly_adapter(G, split, task, config=None, seed=42)

GraphGPS with RWR-calibrated polynomial features.

run_graphgps_ctqw_heat_adapter(G, split, task, config=None, seed=42)

GraphGPS with CTQW-calibrated heat kernel features.

run_graphgps_ctqw_poly_adapter(G, split, task, config=None, seed=42)

GraphGPS with CTQW-calibrated polynomial features.

run_graphgps_dtqw_heat_adapter(G, split, task, config=None, seed=42)

GraphGPS with DTQW-calibrated heat kernel features.

run_graphgps_dtqw_poly_adapter(G, split, task, config=None, seed=42)

GraphGPS with DTQW-calibrated polynomial features.

run_baseline_gcnmf_adapter(G, split, task, config=None, seed=42)

Adapter for baseline GCN-MF (no quantum calibration).

Return type:

Dict[str, float]

run_baseline_filter_adapter(G, split, task, config=None, seed=42)

Adapter for generic baseline filter (defaults to heat kernel).

This is the generic ‘baseline_filter’ method that can be configured to use either heat or polynomial filters via config[‘filter_type’]. Defaults to heat kernel for backward compatibility.

Return type:

Dict[str, float]

run_rwr_fusion_adapter(G, split, task, config=None, seed=42)

Fusion method combining RWR-based embeddings.

Combines: - quvine_rwr (SGNS with RWR) - filter_rwr_heat (RWR-calibrated heat kernel) - filter_rwr_poly (RWR-calibrated polynomial)

Uses SVD-based fusion to combine the three views.

Return type:

Dict[str, float]

run_ctqw_fusion_adapter(G, split, task, config=None, seed=42)

Fusion method combining CTQW-based embeddings.

Combines: - quvine_ctqw (SGNS with CTQW) - filter_ctqw_heat (CTQW-calibrated heat kernel) - filter_ctqw_poly (CTQW-calibrated polynomial)

Uses SVD-based fusion to combine the three views.

Return type:

Dict[str, float]

run_dtqw_fusion_adapter(G, split, task, config=None, seed=42)

Fusion method combining DTQW-based embeddings.

Combines: - quvine_dtqw (SGNS with DTQW) - Baseline heat kernel (as DTQW doesn’t have filter variants) - Baseline polynomial (as DTQW doesn’t have filter variants)

Uses SVD-based fusion to combine the three views. Note: DTQW doesn’t have dedicated filter variants, so we use baseline filters.

Return type:

Dict[str, float]

get_method_adapter(method_name)

Get the adapter function for a method.

Parameters:

method_name (str) – Name of the method

Returns:

Adapter function

Return type:

callable

Raises:

NotImplementedError – If method is not yet implemented