Protein-Protein Interaction (PPI) Framework¶

This framework extends your existing Graffold to support protein-protein interactions with evidence strength modeling. It enables integration of CSV files containing PPI data where the first two columns are UniProt IDs and remaining columns contain link attributes and evidence information.

Architecture Overview¶

Core Components¶

Data Models (src/models/ppi_models.py)
ProteinProteinInteraction: Core PPI data structure
EvidenceScore: Evidence strength modeling
PPIBatchData: Batch processing container
PPINetworkStats: Network statistics
CSV Processor (src/processors/ppi_csv_processor.py)
Flexible column mapping
UniProt ID validation
Evidence type parsing
Confidence thresholding
Database Interface (src/core/ppi_database.py)
Graph database schema extensions (Neo4j or Memgraph)
PPI relationship storage
Evidence tracking
Network querying
Integration Pipeline (src/pipeline/ppi_integration_pipeline.py)
End-to-end processing workflow
Batch processing support
Statistics and reporting

CSV File Format¶

The framework expects CSV files with the following structure:

protein_a_uniprot,protein_b_uniprot,confidence_score,evidence_type,interaction_type,source,method,pubmed_id
P04637,Q13547,0.89,experimental,binding,BioGRID,Y2H,23456789
P01308,P02768,0.67,computational,regulation,STRING,,
P00738,P01133,0.92,literature,complex_formation,IntAct,Co-IP,12345678

Required Columns¶

Column 1: First protein UniProt ID
Column 2: Second protein UniProt ID

Optional Columns (auto-detected)¶

confidence_score/score: Evidence confidence (0.0-1.0)
evidence_type: Type of evidence (experimental, computational, literature, etc.)
interaction_type: Type of interaction (binding, regulation, catalysis, etc.)
source/database: Data source
method: Experimental method
pubmed_id/pmid: PubMed reference
directional: Whether interaction is directional
Any additional columns will be stored as attributes

Quick Start¶

1. Basic Usage¶

from src.pipeline.ppi_integration_pipeline import PPIIntegrationPipeline

# Initialize pipeline
pipeline = PPIIntegrationPipeline(
    min_confidence_threshold=0.3,
    validate_uniprotIDs=True,
    batch_size=1000
)

# Process a single CSV file
result = pipeline.process_csv_file(
    csv_path="data/ppi_interactions.csv",
    source_name="MyPPIDatabase"
)

print(f"Processed {result['interactions_processed']} interactions")

# Get network statistics
stats = pipeline.get_network_statistics()
print(f"Total interactions: {stats.total_interactions}")
print(f"Unique proteins: {stats.unique_proteins}")

pipeline.close()

2. Directory Processing¶

# Process all CSV files in a directory
directory_result = pipeline.process_directory(
    directory_path="data/ppi_datasets/",
    file_pattern="*.csv",
    source_name="MultipleDatasets"
)

print(f"Files processed: {directory_result['files_processed_successfully']}")

3. Validation Before Processing¶

# Validate CSV format before processing
validation = pipeline.validate_csv_format("data/ppi_data.csv")

if validation['is_valid']:
    print("CSV format is valid")
    print(f"Column mapping: {validation['column_mapping']}")
else:
    print(f"Validation errors: {validation['errors']}")

Advanced Configuration¶

Custom Evidence Types and Interaction Types¶

The framework supports extensible evidence and interaction type enums:

from src.models.ppi_models import EvidenceType, InteractionType

# Evidence types include:
# - EXPERIMENTAL, COMPUTATIONAL, LITERATURE, DATABASE
# - CO_EXPRESSION, CO_LOCALIZATION, GENETIC, BIOCHEMICAL
# - PHYSICAL, FUNCTIONAL

# Interaction types include:
# - BINDING, CATALYSIS, REGULATION, PHOSPHORYLATION
# - UBIQUITINATION, COMPLEX_FORMATION, PATHWAY
# - CO_LOCALIZATION, GENETIC_INTERACTION

Database Configuration¶

pipeline = PPIIntegrationPipeline(
    database_uri="bolt://localhost:7687",
    database_user="neo4j",
    database_password="password",
    database_name="ppi_database",
    min_confidence_threshold=0.5,
    validate_uniprotIDs=True,
    batch_size=2000
)

Custom Column Mapping¶

The CSV processor automatically detects common column names, but you can also work with custom formats:

from src.processors.ppi_csv_processor import PPICSVProcessor

processor = PPICSVProcessor(
    uniprot_validation=True,
    min_confidence_threshold=0.2,
    deduplicate=True
)

# The processor automatically maps columns like:
# 'confidence', 'score' -> evidence_score
# 'evidence_type', 'method' -> evidence_type
# 'source', 'database' -> source
# etc.

Data Model Details¶

Evidence Scoring¶

Each interaction can have multiple evidence scores from different sources:

from src.models.ppi_models import EvidenceScore, EvidenceType

evidence = EvidenceScore(
    value=0.85,
    evidence_type=EvidenceType.EXPERIMENTAL,
    source="BioGRID",
    method="Y2H",
    pubmed_id="12345678"
)

Combined Scoring¶

The framework automatically calculates combined confidence scores using weighted evidence:

Experimental evidence: weight 1.0
Biochemical/Physical: weight 0.9
Genetic: weight 0.8
Literature: weight 0.7
Co-localization/Co-expression: weight 0.6
Computational: weight 0.5

Database Schema¶

The framework extends your graph database (Neo4j or Memgraph) with:

Nodes¶

Protein: Enhanced with UniProt IDs and metadata
Evidence: Evidence records linked to interactions

Relationships¶

INTERACTS_WITH: Protein-protein interactions with properties:
interaction_id: Unique identifier
interaction_type: Type of interaction
combined_score: Confidence score
directional: Direction flag
attributes: Additional properties (JSON)
source_database: Data source

Indexes¶

Protein UniProt ID, ID, and name
Interaction ID, score, and type
Evidence type and source

Querying PPI Data¶

Get Protein Interactions¶

from src.core.ppi_database import PPIDatabaseInterface

db = PPIDatabaseInterface()

# Get all interactions for a protein
interactions = db.get_protein_interactions(
    uniprotID="P04637",
    min_confidence=0.5
)

for interaction in interactions:
    print(f"Partner: {interaction['partner_id']}")
    print(f"Score: {interaction['combined_score']}")
    print(f"Type: {interaction['interaction_type']}")

Get Evidence Details¶

# Get evidence for a specific interaction
evidence_list = db.get_interaction_evidence(interaction_id)

for evidence in evidence_list:
    print(f"Evidence: {evidence['evidence_type']}")
    print(f"Score: {evidence['value']}")
    print(f"Source: {evidence['source']}")

Performance Considerations¶

Batch Processing¶

Default batch size: 1000 interactions
Configurable for memory optimization
Progress logging for large datasets

Memory Management¶

Streaming CSV processing
Chunked database operations
Deduplication to prevent duplicates

Indexing¶

Automatic index creation for query performance
UniProt ID indexing for fast protein lookup
Score indexing for confidence-based filtering

Integration with Existing System¶

Compatibility¶

Extends existing DatabaseInterface (supports Neo4j and Memgraph)
Compatible with current configuration system
Uses existing logging framework

Workflow Integration¶

Can be integrated into existing pipelines
Supports the same database instances
Follows existing coding patterns

Error Handling and Validation¶

CSV Validation¶

UniProt ID format checking
Column structure validation
Data type validation
Missing value handling

Processing Errors¶

Graceful error handling
Detailed error logging
Partial success support
Rollback capabilities

Monitoring and Statistics¶

Processing Statistics¶

# Export processing report
pipeline.export_processing_report("reports/ppi_processing_report.json")

# Get real-time statistics
stats = pipeline.get_network_statistics()
print(f"High confidence interactions: {stats.high_confidence_interactions}")
print(f"Evidence distribution: {stats.evidence_type_counts}")

Network Analysis¶

Protein degree distribution
Evidence type distribution
Confidence score analysis
Source database coverage

Example CSV Formats¶

Minimal Format¶

protein_a,protein_b,score
P04637,Q13547,0.89
P01308,P02768,0.67

Rich Format¶

uniprot_a,uniprot_b,confidence_score,evidence_type,interaction_type,source,method,pubmed_id,directional
P04637,Q13547,0.89,experimental,binding,BioGRID,Y2H,23456789,false
P01308,P02768,0.67,computational,regulation,STRING,,25678901,true
P00738,P01133,0.92,literature,complex_formation,IntAct,Co-IP,12345678,false

Custom Attributes¶

protein1,protein2,confidence,evidence,custom_score,pathway,tissue_specific
P04637,Q13547,0.89,experimental,8.5,p53_pathway,brain
P01308,P02768,0.67,computational,6.2,insulin_signaling,liver

Cleanup and Maintenance¶

Data Cleanup¶

# Remove all PPI data
deleted_count = pipeline.cleanup_database()

# Remove data from specific source
deleted_count = pipeline.cleanup_database(source_database="old_dataset")

Statistics Reset¶

# Get fresh statistics after cleanup
stats = pipeline.get_network_statistics()

This framework provides a robust, scalable solution for integrating protein-protein interaction data into your existing knowledge graph system while maintaining compatibility with your current protein-disease relationship data.