qbiocode.apps.quvine.fusion.fuse module

Summary

Functions:

fuse_best_across_types	Fuse best-performing method from each type.
fuse_by_method_type	Fuse embeddings within a method type.
fuse_embeddings	Fuse multiple embeddings using various methods.
fuse_embeddings_attention	Attention-based fusion: learn attention weights for each embedding view.
fuse_embeddings_graphreg	Solve: argmin_U ||U - Zbar||_F^2 + beta * tr(U^T L U) + lam ||U||_F^2 where Zbar is the SVD-fused initialization projected to k dims.
fuse_embeddings_hybrid	Hybrid fusion: combines SVD and attention-based fusion.
fuse_embeddings_svd	Fast early fusion: concatenate (after per-block normalization) + SVD/PCA to shared k-dim space.
fuse_embeddings_svd_shared_private	SVD-based shared/private fusion for N ≥ 2 embedding views.
hierarchical_fusion	Perform hierarchical fusion strategy for all 39 methods.

Reference

fuse_embeddings_svd(Zs, k)

Fast early fusion: concatenate (after per-block normalization) + SVD/PCA to shared k-dim space.

fuse_embeddings_graphreg(Zs, k, L, beta=0.01, lam=0.01, max_cg_iter=200, cg_tol=1e-06)

Solve: argmin_U ||U - Zbar||_F^2 + beta * tr(U^T L U) + lam ||U||_F^2 where Zbar is the SVD-fused initialization projected to k dims.

This is a much simpler regularization story than your full multiview + Ws + alpha, and it avoids over-parameterization reviewers will question.

fuse_embeddings_attention(Zs, k, temperature=1.0)

Attention-based fusion: learn attention weights for each embedding view.

Uses softmax attention over embedding similarities to weight each view.

fuse_embeddings_hybrid(Zs, k, L=None, beta=0.01, lam=0.01, temperature=1.0)

Hybrid fusion: combines SVD and attention-based fusion.

First applies attention-weighted fusion, then applies SVD with optional graph regularization.

fuse_embeddings_svd_shared_private(Zs, k, gate_type='attention')

SVD-based shared/private fusion for N ≥ 2 embedding views.

Each view is decomposed into a shared component (extracted by a joint rank-k SVD over all views concatenated) and a private residual. The views are then recombined using one of two gating strategies:

attention — a per-feature sigmoid gate is applied to each view’s

private component; the result is added to the mean shared component. Good when views are complementary and private details matter.

moe — a per-node softmax over the V views selects a weighted

combination of all normalised views. Good when views are exchangeable and the model should pick the most informative one per node.

Parameters:

• Zs (list of np.ndarray, each (n, d)) – Embedding views to fuse (V ≥ 2).

• k (int) – Rank for SVD approximation (typically d // 4).

• gate_type ({'attention', 'moe'})

Returns:

Z_final

Return type:

np.ndarray, shape (n, d)

fuse_embeddings(store, k=None, L=None, method='svd', beta=0.01, lam=0.01, temperature=1.0, svd_rank=None, gate_type='attention')

Fuse multiple embeddings using various methods.

Parameters:

• store (EmbeddingStore) – Store containing multiple embeddings

• k (int, optional) – Target embedding dimension

• L (sparse matrix, optional) – Graph Laplacian (required for ‘graphreg’ and ‘hybrid’)

• method (str) – Fusion method: - “svd” : SVD-based fusion (fast, default) - “graphreg” : Graph-regularized fusion (requires L) - “attention” : Attention-weighted fusion - “hybrid” : Attention + graph regularization (requires L) - “svd_shared_priv” : SVD shared/private decomposition with gating - “all” : Compute all methods (requires L)

• beta (float) – Graph regularization strength

• lam (float) – L2 regularization strength

• temperature (float) – Temperature for attention softmax

• svd_rank (int, optional) – Rank for SVD approximation in shared/private decomposition (default: k // 4)

• gate_type (str) – Gate type for shared/private fusion: ‘attention’ or ‘moe’

Returns:

• embeddings (list) – List of fused embeddings

• names (list) – List of method names

fuse_by_method_type(embeddings_dict, method_type, quantum_only=False, classical_only=False, fusion_method='svd', target_dim=None)

Fuse embeddings within a method type.

Parameters:

• embeddings_dict – {method_name: embedding_array}

• method_type – Type of methods to fuse (‘sgns’, ‘filter’, ‘gat’, ‘graphgps’, ‘baselines’)

• quantum_only – Only fuse quantum methods

• classical_only – Only fuse classical methods

• fusion_method – ‘svd’, ‘concatenate’, ‘average’

• target_dim – Target dimension for fused embedding

Returns:

Fused embedding array

fuse_best_across_types(embeddings_dict, performance_scores, quantum_only=False, classical_only=False, fusion_method='svd', target_dim=None)

Fuse best-performing method from each type.

Steps:

1. For each method type (SGNS, Filter, GAT, GraphGPS):

   • Select best-performing method based on scores

2. Fuse the best methods using specified fusion method

Parameters:

• embeddings_dict – {method_name: embedding}

• performance_scores – {method_name: score} (mean across replicates)

• quantum_only – Only consider quantum methods

• classical_only – Only consider classical methods

• fusion_method – ‘svd’, ‘concatenate’, ‘average’

• target_dim – Target dimension for fused embedding

Returns:

Fused embedding from best methods across types

hierarchical_fusion(embeddings_dict, performance_scores, target_dim=None)

Perform hierarchical fusion strategy for all 39 methods.

Strategy:

1. Within-type fusion:

   • Fuse quantum methods per type → fused_quantum_{type}

   • Fuse classical methods per type → fused_classical_{type}

2. Cross-type fusion:

   • Select best quantum method per type

   • Select best classical method per type

   • Fuse best quantum methods → fused_q

   • Fuse best classical methods → fused_c

Parameters:

• embeddings_dict – {method_name: embedding_array}

• performance_scores – {method_name: score}

• target_dim – Target dimension for fused embeddings

Returns:

Fused embeddings, under these keys

• ’fused_quantum_sgns’, ‘fused_classical_sgns’

• ’fused_quantum_filter’, ‘fused_classical_filter’

• ’fused_quantum_gat’, ‘fused_classical_gat’

• ’fused_quantum_graphgps’, ‘fused_classical_graphgps’

• ’fused_q’ (best quantum across types)

• ’fused_c’ (best classical across types)

Return type:

dict