Multi-Source PPI Integration Guide¶

This guide explains how to handle multiple PPI CSV files from different sources (like FunCoup vs STRING) while preserving source-specific attributes and evidence strength.

Overview¶

The enhanced multi-source PPI framework provides three key capabilities:

Source Attribution: Each interaction maintains its source database information
Evidence Merging: Combine evidence from multiple sources for the same protein pair
Attribute Preservation: Keep source-specific attributes separate and queryable

Multi-Source Integration Strategies¶

1. Merge Evidence Strategy (`merge_evidence`)¶

Best for: Combining complementary data sources to get comprehensive protein interaction networks

from src.pipeline.multisource_ppi_pipeline import MultiSourcePPIPipeline

pipeline = MultiSourcePPIPipeline(merge_strategy="merge_evidence")

source_configs = [
    {
        'name': 'STRING',
        'path': 'data/string_interactions.csv',
        'evidence_type': 'computational'
    },
    {
        'name': 'FunCoup', 
        'path': 'data/funcoup_interactions.csv',
        'evidence_type': 'computational'
    },
    {
        'name': 'BioGRID',
        'path': 'data/biogrid_interactions.csv', 
        'evidence_type': 'experimental'
    }
]

results = pipeline.process_source_directory(source_configs)

How it works: - For each protein pair, creates a single relationship - Combines evidence scores from all sources - Merges attributes by source (e.g., source_STRING, source_FunCoup) - Uses highest combined confidence score

Database schema:

(ProteinA)-[INTERACTS_WITH {
    combined_score: 0.85,
    attributes: {
        "source_STRING": {"neighborhood": 0.12, "coexpression": 0.73},
        "source_FunCoup": {"tissue_specificity": "brain", "class": "high"}
    }
}]-(ProteinB)

(Evidence {source: "STRING", value: 0.82, evidence_type: "computational"})
(Evidence {source: "FunCoup", value: 0.78, evidence_type: "computational"})
(Evidence {source: "BioGRID", value: 0.91, evidence_type: "experimental"})

2. Update Best Strategy (`update_best`)¶

Best for: When you want only the highest confidence interaction per protein pair

pipeline = MultiSourcePPIPipeline(merge_strategy="update_best")

How it works: - Keeps only the interaction with the highest confidence score - Replaces lower-confidence interactions with better ones - Useful when sources have varying quality

3. Preserve All Strategy (`preserve_all`)¶

Best for: When you need to maintain separate relationships for each source

pipeline = MultiSourcePPIPipeline(merge_strategy="preserve_all")

How it works: - Creates separate relationships for each source - Allows multiple INTERACTS_WITH relationships between same proteins - Preserves all source-specific information

Database schema:

(ProteinA)-[INTERACTS_WITH {source_database: "STRING", score: 0.82}]-(ProteinB)
(ProteinA)-[INTERACTS_WITH {source_database: "FunCoup", score: 0.78}]-(ProteinB)
(ProteinA)-[INTERACTS_WITH {source_database: "BioGRID", score: 0.91}]-(ProteinB)

CSV File Format Examples¶

STRING Database Format¶

protein1,protein2,combined_score,neighborhood,fusion,cooccurence,coexpression,experimental,database,textmining
P04637,Q13547,892,0,0,78,412,67,900,356
P01308,P02768,756,45,0,0,234,123,800,123

FunCoup Database Format¶

proteinA,proteinB,confidence,evidence_type,link_type,species,tissue_specificity
P04637,Q13547,0.845,experimental,binding,human,brain
P01308,P02768,0.723,coexpression,regulation,human,liver

BioGRID Database Format¶

Official Symbol Interactor A,Official Symbol Interactor B,Confidence Score,Experimental System,Source Database,Pubmed ID
P04637,Q13547,0.95,Two-hybrid,BioGRID,12345678
P01308,P02768,0.88,Co-immunoprecipitation,BioGRID,23456789

Custom Database Format¶

uniprot_a,uniprot_b,score,method,tissue,disease_relevance,custom_metric,pathway
P04637,Q13547,0.89,Y2H,brain,cancer,8.5,p53_signaling
P01308,P02768,0.78,Co-IP,liver,diabetes,7.2,insulin_pathway

Source-Specific Attribute Access¶

Query Source-Specific Data¶

from src.core.multisource_ppi_database import MultiSourcePPIDatabaseInterface

db = MultiSourcePPIDatabaseInterface()

# Get all interactions between two proteins with source breakdown
interactions = db.get_interaction_by_sources("P04637", "Q13547")

for interaction in interactions:
    print(f"Combined score: {interaction['combined_score']}")

    # Access source-specific attributes
    source_data = interaction['source_specific_data']
    for src_info in source_data:
        source_name = src_info['source']
        attributes = src_info['attributes']

        print(f"\n{source_name} attributes:")
        for attr_key, attr_value in attributes.items():
            print(f"  {attr_key}: {attr_value}")

Example output:

Combined score: 0.856

STRING attributes:
  neighborhood: 0.12
  coexpression: 0.73
  experimental: 0.67
  textmining: 0.45

FunCoup attributes:
  tissue_specificity: brain
  link_type: binding
  evolutionary_score: 0.91

BioGRID attributes:
  experimental_system: Two-hybrid
  pubmed_id: 12345678
  throughput: Low Throughput

Compare Sources¶

# Compare overlap between two sources
comparison = db.get_source_comparison("STRING", "FunCoup")

print(f"Common interactions: {comparison['common_interactions']}")
print("Detailed comparison:")
for detail in comparison['details']:
    print(f"  {detail['protein_a']} - {detail['protein_b']}")
    print(f"    STRING score: {detail['source_a_attrs'].get('combined_score', 'N/A')}")
    print(f"    FunCoup score: {detail['source_b_attrs'].get('confidence', 'N/A')}")

Network Statistics for Multi-Source Data¶

# Get enhanced statistics
stats = db.get_multisource_network_stats()

print(f"Total relationships: {stats['total_relationships']}")
print(f"Unique sources: {stats['unique_sources']}")
print(f"Multi-source protein pairs: {stats['multi_source_pairs']}")
print(f"Average sources per pair: {stats['avg_sources_per_pair']:.2f}")

print("\nSource distribution:")
for source, count in stats['source_distribution'].items():
    print(f"  {source}: {count} interactions")

Processing Multiple Source Directories¶

# Process multiple sources at once
source_configs = [
    {
        'name': 'STRING',
        'path': '/data/string_v11/',
        'file_pattern': '*.protein.links.v11.0.txt',
        'evidence_type': 'computational'
    },
    {
        'name': 'FunCoup5',
        'path': '/data/funcoup/',
        'file_pattern': 'FC5.0_H.sapiens_*.gz',
        'evidence_type': 'computational'
    },
    {
        'name': 'BioGRID',
        'path': '/data/biogrid/BIOGRID-ALL-4.4.210.tab3.txt',
        'evidence_type': 'experimental'
    }
]

pipeline = MultiSourcePPIPipeline(
    merge_strategy="merge_evidence",
    min_confidence_threshold=0.4
)

results = pipeline.process_source_directory(source_configs)

# Export comprehensive report
pipeline.export_multisource_report("reports/multisource_analysis.json")

Best Practices¶

1. Source Configuration¶

Use descriptive source names (e.g., "STRING_v11", "FunCoup5.0")
Set appropriate evidence types for each source
Configure source-specific confidence thresholds if needed

2. Merge Strategy Selection¶

Use merge_evidence when sources are complementary (e.g., experimental + computational)
Use update_best when sources overlap and you want highest quality
Use preserve_all when you need to analyze source-specific differences

3. Confidence Thresholds¶

Set per-source thresholds based on data quality
STRING: typically 0.4-0.7 for medium-high confidence
BioGRID: typically 0.0 (all experimental data)
FunCoup: typically 0.5-0.8 depending on evidence class

4. Attribute Mapping¶

Map source-specific column names to standard attributes
Preserve unique attributes (e.g., experimental methods, tissue specificity)
Use consistent naming conventions across sources

Advanced Querying¶

Find Proteins with Most Sources¶

MATCH (p:Protein)-[r:INTERACTS_WITH]-()
WITH p, count(DISTINCT r.source_database) as source_count
WHERE source_count >= 3
RETURN p.uniprotID, source_count
ORDER BY source_count DESC

Source-Specific High-Confidence Interactions¶

MATCH ()-[r:INTERACTS_WITH]-()
WHERE r.source_database = "BioGRID" AND r.combined_score >= 0.9
RETURN count(r) as high_conf_biogrid

Cross-Source Evidence Validation¶

MATCH (a:Protein)-[r1:INTERACTS_WITH]-(b:Protein)
MATCH (a)-[r2:INTERACTS_WITH]-(b)
WHERE r1.source_database = "STRING" AND r2.source_database = "BioGRID"
RETURN a.uniprotID, b.uniprotID, 
       r1.combined_score as string_score,
       r2.combined_score as biogrid_score

Integration with Existing System¶

The multi-source PPI framework seamlessly integrates with your existing protein-disease system:

Same graph database: Uses your existing Neo4j or Memgraph instance
Compatible schema: Extends current protein nodes
Unified querying: Query both PPI and protein-disease relationships together
Existing configuration: Uses your current database connection settings

This allows you to build comprehensive protein networks that include both disease associations and protein-protein interactions from multiple high-quality sources.