qbiocode.apps.quvine.baselines.gcn_mf module#

GCN-MF: Graph Convolutional Network with Matrix Factorization

A baseline method for disease gene prioritization that combines: 1. Graph Convolutional Networks (GCN) for learning node representations 2. Matrix Factorization for capturing latent features

Reference: - Kipf & Welling (2017). Semi-Supervised Classification with Graph Convolutional Networks - Matrix factorization approaches for biological network analysis

Summary#

Classes:

GCNLayer

Single Graph Convolutional Layer.

GCNMF

GCN-MF: Graph Convolutional Network with Matrix Factorization.

QuVINEGCNMF

QuVINE GCN-MF: GCN-MF with precomputed quantum-calibrated features.

Functions:

generate_baseline_filter_embedding_wrapper

Generate baseline graph filter embeddings (WITHOUT quantum calibration).

generate_baseline_gcnmf_embedding

Generate baseline GCN-MF embeddings (WITHOUT quantum calibration).

generate_qcaliber_gcnmf_heat_embedding

Generate QuVINE Heat+GCN-MF (HGCNMF) embeddings.

generate_qcaliber_gcnmf_poly_embedding

Generate QuVINE Polynomial+GCN-MF (PGCNMF) embeddings.

generate_quvine_gcnmf_embedding

Generate QuVINE GCN-MF embeddings (Heat or Poly variant).

normalize_adjacency

Normalize adjacency matrix: D^(-1/2) * A * D^(-1/2)

precompute_quantum_diffusion

Precompute quantum-calibrated diffusion OFFLINE (before training).

train_gcn_mf

Train GCN-MF model.

Reference#

class GCNLayer(in_features, out_features, bias=True)[source]#

Bases: Module

Single Graph Convolutional Layer.

reset_parameters()[source]#

Initialize parameters.

forward(x, adj)[source]#

Forward pass.

Parameters:

  • x – Node features [N, in_features]

  • adj – Normalized adjacency matrix [N, N] (sparse or dense)

Returns:

Output features [N, out_features]

class GCNMF(n_nodes, input_dim, hidden_dim, output_dim, mf_dim=64, n_layers=2, dropout=0.5)[source]#

Bases: Module

GCN-MF: Graph Convolutional Network with Matrix Factorization.

Architecture: 1. GCN layers for learning graph-based representations 2. Matrix factorization component for latent features 3. Fusion of GCN and MF representations

__init__(n_nodes, input_dim, hidden_dim, output_dim, mf_dim=64, n_layers=2, dropout=0.5)[source]#

Initialize GCN-MF model.

Parameters:

  • n_nodes – Number of nodes in the graph

  • input_dim – Input feature dimension

  • hidden_dim – Hidden layer dimension

  • output_dim – Output dimension (number of classes)

  • mf_dim – Matrix factorization embedding dimension

  • n_layers – Number of GCN layers

  • dropout – Dropout rate

forward(x, adj, node_indices=None)[source]#

Forward pass.

Parameters:

  • x – Node features [N, input_dim]

  • adj – Normalized adjacency matrix [N, N]

  • node_indices – Optional node indices for batch processing

Returns:

Output predictions [N, output_dim]

get_embeddings(x, adj)[source]#

Get node embeddings (before classification layer).

Parameters:

  • x – Node features

  • adj – Normalized adjacency matrix

Returns:

Node embeddings

normalize_adjacency(adj)[source]#

Normalize adjacency matrix: D^(-1/2) * A * D^(-1/2)

Parameters:

adj – Adjacency matrix (scipy sparse or numpy array)

Returns:

Normalized adjacency matrix

precompute_quantum_diffusion(X, L, diffusion_type='heat', t_star=None, poly_coeffs=None)[source]#

Precompute quantum-calibrated diffusion OFFLINE (before training).

This function should be called ONCE before training to compute diffused features. The result is then passed to QuVINEGCNMF during training.

Parameters:

  • X – Original node features [N, input_dim] (numpy array or torch tensor)

  • L – Laplacian matrix (scipy sparse or numpy array)

  • diffusion_type – ‘heat’ or ‘poly’

  • t_star – Calibrated heat kernel time parameter (for heat diffusion)

  • poly_coeffs – Calibrated polynomial coefficients (for polynomial diffusion)

Returns:

Diffused features [N, input_dim] (torch tensor)

Return type:

X_diffused

Example

>>> # Offline: Compute diffusion once
>>> X_diffused_heat = precompute_quantum_diffusion(X, L, 'heat', t_star=0.5)
>>> X_diffused_poly = precompute_quantum_diffusion(X, L, 'poly', poly_coeffs=coeffs)
>>>
>>> # Online: Use in training (no diffusion computation)
>>> model = QuVINEGCNMF(n_nodes, input_dim, hidden_dim, output_dim)
>>> output = model(X_diffused_heat, adj)  # Fast!
class QuVINEGCNMF(n_nodes, input_dim, hidden_dim, output_dim, mf_dim=64, n_layers=2, dropout=0.5)[source]#

Bases: GCNMF

QuVINE GCN-MF: GCN-MF with precomputed quantum-calibrated features.

DESIGN PHILOSOPHY: - Diffusion is computed ONCE offline (before training) - Diffused features are passed as input - No CPU conversion or diffusion computation during training - Scalable and efficient for large graphs

This model expects precomputed diffused features as input, combining: 1. Precomputed quantum-calibrated diffusion (offline) 2. GCN layers for learning representations (online) 3. Matrix factorization for latent features (online)

__init__(n_nodes, input_dim, hidden_dim, output_dim, mf_dim=64, n_layers=2, dropout=0.5)[source]#

Initialize QuVINE GCN-MF model.

Parameters:

  • n_nodes – Number of nodes

  • input_dim – Input feature dimension (should match diffused features)

  • hidden_dim – Hidden layer dimension

  • output_dim – Output dimension

  • mf_dim – Matrix factorization dimension

  • n_layers – Number of GCN layers

  • dropout – Dropout rate

Note

This model expects precomputed diffused features as input. Compute diffusion offline using:

X_diffused = apply_quantum_diffusion(X, L, t_star, poly_coeffs)

Then pass X_diffused to forward().

forward(x, adj, node_indices=None)[source]#

Forward pass with precomputed diffused features.

Parameters:

  • x – PRECOMPUTED diffused features [N, input_dim] (computed offline before training)

  • adj – Normalized adjacency matrix [N, N]

  • node_indices – Optional node indices

Returns:

Output predictions [N, output_dim]

Note

x should be the result of offline diffusion: x = exp(-t*L) @ X_original (heat kernel) or x = polynomial_filter(L, coeffs) @ X_original (polynomial)

get_embeddings(x, adj)[source]#

Get node embeddings from precomputed diffused features.

Parameters:

  • x – PRECOMPUTED diffused features [N, input_dim] (computed offline before training)

  • adj – Normalized adjacency matrix

Returns:

Node embeddings

Note

x should already be diffused features from offline computation. No diffusion is applied here - it’s done offline!

train_gcn_mf(model, x, y, adj, train_mask, val_mask, epochs=200, lr=0.01, weight_decay=0.0005, patience=20)[source]#

Train GCN-MF model.

Parameters:

  • model – GCN-MF model

  • x – Node features

  • y – Labels

  • adj – Normalized adjacency matrix

  • train_mask – Training mask

  • val_mask – Validation mask

  • epochs – Number of training epochs

  • lr – Learning rate

  • weight_decay – Weight decay for regularization

  • patience – Early stopping patience

Returns:

Dictionary with training history

generate_quvine_gcnmf_embedding(G, q_targets, embedding_dim=128, diffusion_type='heat', t_star=None, poly_coeffs=None, K=4, ridge=1e-06, hidden_dim=64, mf_dim=64, n_layers=2, epochs=200, lr=0.01, weight_decay=0.0005, normalize_laplacian=True, random_state=42)[source]#

Generate QuVINE GCN-MF embeddings (Heat or Poly variant).

WORKFLOW: 1. Calibrate diffusion parameters using quantum walks (if not provided) 2. Precompute diffused features OFFLINE 3. Train GCN-MF model with diffused features 4. Extract final embeddings

This is a HIGH-LEVEL wrapper that combines: - QuVINE quantum filter calibration (from quantum_filters.py) - Offline diffusion precomputation - GCN-MF training - Embedding extraction

Parameters:

  • G – NetworkX graph

  • q_targets – List of quantum walk targets for calibration Format: [{‘nodes’: […], ‘center’: int, ‘pQ’: array}, …]

  • embedding_dim – Final embedding dimension

  • diffusion_type – ‘heat’ or ‘poly’

  • t_star – Pre-calibrated heat kernel time (optional, will calibrate if None)

  • poly_coeffs – Pre-calibrated polynomial coefficients (optional)

  • K – Polynomial degree (for poly diffusion)

  • ridge – Ridge regularization for polynomial calibration

  • hidden_dim – GCN hidden dimension

  • mf_dim – Matrix factorization dimension

  • n_layers – Number of GCN layers

  • epochs – Training epochs

  • lr – Learning rate

  • weight_decay – Weight decay for regularization

  • normalize_laplacian – Whether to normalize Laplacian

  • random_state – Random seed

Returns:

Node embeddings [N, embedding_dim] metadata: Dictionary with calibration info and training history

Return type:

embeddings

Example

>>> from qbiocode.apps.quvine.baselines.gcn_mf import generate_quvine_gcnmf_embedding
>>>
>>> # Generate QuVINE GCN-MF (Heat) embeddings
>>> embeddings_heat, meta_heat = generate_quvine_gcnmf_embedding(
...     G, q_targets, embedding_dim=128, diffusion_type='heat'
... )
>>>
>>> # Generate QuVINE GCN-MF (Poly) embeddings
>>> embeddings_poly, meta_poly = generate_quvine_gcnmf_embedding(
...     G, q_targets, embedding_dim=128, diffusion_type='poly', K=4
... )
generate_qcaliber_gcnmf_heat_embedding(G, q_targets, embedding_dim=128, t_star=None, **kwargs)[source]#

Generate QuVINE Heat+GCN-MF (HGCNMF) embeddings.

Convenience wrapper for heat kernel variant.

Parameters:

  • G – NetworkX graph

  • q_targets – Quantum walk targets for calibration

  • embedding_dim – Embedding dimension

  • t_star – Pre-calibrated time parameter (optional)

  • **kwargs – Additional arguments for generate_qcaliber_gcnmf_embedding

Returns:

Node embeddings [N, embedding_dim] metadata: Calibration and training info

Return type:

embeddings

generate_qcaliber_gcnmf_poly_embedding(G, q_targets, embedding_dim=128, poly_coeffs=None, K=4, ridge=1e-06, **kwargs)[source]#

Generate QuVINE Polynomial+GCN-MF (PGCNMF) embeddings.

Convenience wrapper for polynomial filter variant.

Parameters:

  • G – NetworkX graph

  • q_targets – Quantum walk targets for calibration

  • embedding_dim – Embedding dimension

  • poly_coeffs – Pre-calibrated coefficients (optional)

  • K – Polynomial degree

  • ridge – Ridge regularization

  • **kwargs – Additional arguments for generate_qcaliber_gcnmf_embedding

Returns:

Node embeddings [N, embedding_dim] metadata: Calibration and training info

Return type:

embeddings

generate_baseline_gcnmf_embedding(G, embedding_dim=128, hidden_dim=64, mf_dim=64, n_layers=2, epochs=200, lr=0.01, weight_decay=0.0005, random_state=42, device='cpu')[source]#

Generate baseline GCN-MF embeddings (WITHOUT quantum calibration).

This serves as a classical baseline to compare against QuVINE methods. Uses standard GCN-MF without any quantum-calibrated diffusion.

Parameters:

  • G (Graph) – NetworkX graph

  • embedding_dim (int) – Final embedding dimension

  • hidden_dim (int) – GCN hidden dimension

  • mf_dim (int) – Matrix factorization dimension

  • n_layers (int) – Number of GCN layers

  • epochs (int) – Training epochs

  • lr (float) – Learning rate

  • weight_decay (float) – L2 regularization

  • random_state (int) – Random seed

Return type:

ndarray

Returns:

Node embeddings [N, embedding_dim]

Example

>>> import networkx as nx
>>> from qbiocode.apps.quvine.baselines.gcn_mf import generate_baseline_gcnmf_embedding
>>>
>>> G = nx.karate_club_graph()
>>> embeddings = generate_baseline_gcnmf_embedding(G, embedding_dim=128)
>>> print(embeddings.shape)  # (34, 128)
generate_baseline_filter_embedding_wrapper(G, filter_type='heat', t=1.0, K=4, embedding_dim=128, normalize=True, random_state=42)[source]#

Generate baseline graph filter embeddings (WITHOUT quantum calibration).

Wrapper for the baseline filter function in quantum_filters.py. This serves as a classical baseline to compare against QuVINE methods.

Parameters:

  • G (Graph) – NetworkX graph

  • filter_type (str) – Type of filter (‘heat’ or ‘poly’)

  • t (float) – Time parameter for heat kernel (if filter_type=’heat’)

  • K (int) – Polynomial degree (if filter_type=’poly’)

  • embedding_dim (int) – Embedding dimension

  • normalize (bool) – Whether to normalize Laplacian

  • random_state (int) – Random seed

Return type:

ndarray

Returns:

Node embeddings [N, embedding_dim]

Example

>>> import networkx as nx
>>> from qbiocode.apps.quvine.baselines.gcn_mf import generate_baseline_filter_embedding_wrapper
>>>
>>> G = nx.karate_club_graph()
>>>
>>> # Heat kernel baseline
>>> embeddings_heat = generate_baseline_filter_embedding_wrapper(
...     G, filter_type='heat', t=1.0, embedding_dim=128
... )
>>>
>>> # Polynomial filter baseline
>>> embeddings_poly = generate_baseline_filter_embedding_wrapper(
...     G, filter_type='poly', K=4, embedding_dim=128
... )