pandaprot 1.1.0

A tool for mapping protein-protein, protein-nucleic acid, and antigen-antibody interactions

PandaProt

A comprehensive Python application for mapping and visualizing molecular interactions at protein/nucleic acid interfaces. A tool for mapping protein-protein, protein-nucleic acid, and antigen-antibody interactions.

Comprehensive Interaction Mapping

PandaProt can detect and analyze a comprehensive set of molecular interactions that occur in protein/DNA structures:

Standard Interactions:

• Hydrogen Bonds: Between hydrogen donors and acceptors (N-H···O, O-H···O, etc.)
• Ionic Interactions: Between oppositely charged residues (Arg/Lys/His with Asp/Glu)
• Hydrophobic Interactions: Between non-polar side chains
• Pi-Pi Stacking: Between aromatic rings (parallel, T-shaped, offset-stacked)
• Pi-Cation Interactions: Between aromatic rings and cationic groups
• Salt Bridges: Close-range ionic interactions forming "bridges"

Enhanced Interactions:

• Cation-Pi Interactions: Between cations and aromatic rings
• CH-Pi Interactions: Between CH groups and aromatic rings
• Disulfide Bridges: Covalent bonds between cysteine residues
• Sulfur-Aromatic Interactions: Between sulfur atoms and aromatic rings
• Water-Mediated Interactions: Hydrogen bonds bridged by water molecules
• Metal-Coordinated Bonds: Interactions mediated by metal ions
• Halogen Bonds: Between halogen atoms and Lewis bases
• Amide-Aromatic Interactions: Between amide groups and aromatic rings
• Van der Waals Interactions: Non-specific attractive forces
• Amide-Amide Hydrogen Bonds: Between backbone or side chain amide groups

Intuitive Visualization

• Interactive 3D Visualization: Color-coded display of interactions in the 3D structure
• Network Analysis: Graph representation of interaction networks
• Detailed Reports: Comprehensive interaction statistics and measurements

Installation

pip install pandaprot

Usage

Command Line Interface

pandaprot -h
usage: pandaprot [-h] [--chains CHAINS [CHAINS ...]] [--3d-plot] [--export-vis] [--report] [--network] [--output OUTPUT]
                 [--distance-cutoff DISTANCE_CUTOFF] [--include-intrachain] [--all-interactions] [--standard-only]
                 [--hydrogen-bonds] [--ionic] [--hydrophobic] [--pi-stacking] [--pi-cation] [--salt-bridges] [--cation-pi]
                 [--ch-pi] [--disulfide] [--sulfur-aromatic] [--water-mediated] [--metal-coordination] [--halogen-bonds]
                 [--amide-aromatic] [--van-der-waals] [--amide-amide] [--statistics] [--residue-summary]
                 pdb_file

PandaProt: Comprehensive Protein Interaction Mapper

positional arguments:
  pdb_file              Path to PDB file

options:
  -h, --help            show this help message and exit
  --chains CHAINS [CHAINS ...]
                        Chains to analyze (e.g., A B)
  --3d-plot             Generate 3D visualization
  --export-vis          Export visualization files for PyMOL, Chimera, VMD, and Molstar
  --report              Generate detailed interaction report
  --network             Generate interaction network visualization
  --output, -o OUTPUT   Output file prefix
  --distance-cutoff DISTANCE_CUTOFF
                        Distance cutoff for interaction detection (default: 4.5Å)
  --include-intrachain  Include intra-chain interactions

Interaction Types:
  --all-interactions    Map all interaction types (default)
  --standard-only       Map only standard interactions (H-bonds, ionic, hydrophobic, pi-stacking, salt bridges)
  --hydrogen-bonds      Map hydrogen bonds
  --ionic               Map ionic interactions
  --hydrophobic         Map hydrophobic interactions
  --pi-stacking         Map pi-pi stacking interactions
  --pi-cation           Map pi-cation interactions
  --salt-bridges        Map salt bridges
  --cation-pi           Map cation-pi interactions
  --ch-pi               Map CH-pi interactions
  --disulfide           Map disulfide bridges
  --sulfur-aromatic     Map sulfur-aromatic interactions
  --water-mediated      Map water-mediated interactions
  --metal-coordination  Map metal-coordinated bonds
  --halogen-bonds       Map halogen bonds
  --amide-aromatic      Map amide-aromatic interactions
  --van-der-waals       Map van der Waals interactions
  --amide-amide         Map amide-amide hydrogen bonds

Analysis Options:
  --statistics          Generate interaction statistics
  --residue-summary     Generate residue interaction summary

Full command

pandaprot 4kpy.pdb --export-vis  --3d-plot --report --network --statistics --residue-summary --chains A B C D E F --output protein-dna-ligand

pandaprot 1BJ1.pdb --3d-plot --export-vis  --report --network --statistics --residue-summary --chains L H V W J K  --output antigen_antibody

# Basic usage - map all interactions
pandaprot example.pdb

# Analyze specific chains
pandaprot example.pdb --chains A B

# Generate 3D visualization
pandaprot example.pdb --3d-plot

# Generate detailed report
pandaprot example.pdb --report

# Generate interaction network
pandaprot example.pdb --network

# Map specific interaction types
pandaprot example.pdb --hydrogen-bonds --ionic --salt-bridges

# Map only standard interactions
pandaprot example.pdb --standard-only

# Include water-mediated and metal-coordinated interactions
pandaprot example.pdb --water-mediated --metal-coordination

# Generate interaction statistics
pandaprot example.pdb --statistics

# Specify output file prefix
pandaprot example.pdb --3d-plot --report --network --output myresults

# Include intra-chain interactions
pandaprot example.pdb --include-intrachain

Python API

from pandaprot import PandaProt

# Initialize with PDB file
analyzer = PandaProt("example.pdb", chains=["A", "B"])

# Map all interactions
interactions = analyzer.map_interactions()

# Map with custom parameters
interactions = analyzer.map_interactions(
    distance_cutoff=4.5,
    include_intrachain=False
)

# Filter interactions
filtered = analyzer.filter_interactions(
    interaction_types=["hydrogen_bonds", "salt_bridges"],
    chains=["A"],
    distance_range=(2.5, 3.5)
)

# Generate 3D visualization
analyzer.visualize_3d("visualization.html")

# Visualize specific interaction types
analyzer.visualize_3d(
    "hbonds_visualization.html", 
    interaction_types=["hydrogen_bonds", "water_mediated"]
)

# Generate detailed report
report = analyzer.generate_report("report.csv")

# Generate report for specific interaction types
report = analyzer.generate_report(
    "ionic_report.csv",
    interaction_types=["ionic_interactions", "salt_bridges"]
)

# Create interaction network
graph, fig = analyzer.create_interaction_network("network.png")

# Get interaction statistics
stats = analyzer.get_interaction_statistics()
print(f"Total interactions: {stats['total_interactions']}")
print(f"Most interactive residue: {list(stats['residue_frequencies'].keys())[0]}")

Example Applications

Antibody-Antigen Interaction Analysis

# Analyze an antibody-antigen complex
analyzer = PandaProt("antibody_complex.pdb", chains=["H", "L", "A"])

# Map all interactions
interactions = analyzer.map_interactions()

# Find epitope residues (antigen residues interacting with antibody)
epitope_residues = []
for interaction_type, interactions_list in interactions.items():
    for interaction in interactions_list:
        # Extract chain information from interaction
        chain1 = interaction.get('chain1', interaction.get('donor_chain', ''))
        chain2 = interaction.get('chain2', interaction.get('acceptor_chain', ''))
        
        # Extract residue information
        res1 = interaction.get('residue1', interaction.get('donor_residue', ''))
        res2 = interaction.get('residue2', interaction.get('acceptor_residue', ''))
        
        # Check if antigen (chain A) is interacting with antibody (chains H or L)
        if chain1 == 'A' and chain2 in ['H', 'L']:
            epitope_residues.append(f"A:{res1}")
        elif chain2 == 'A' and chain1 in ['H', 'L']:
            epitope_residues.append(f"A:{res2}")

# Get unique epitope residues
epitope_residues = list(set(epitope_residues))
print(f"Epitope residues: {', '.join(epitope_residues)}")

Protein-Protein Interface Analysis

# Analyze a protein-protein complex
analyzer = PandaProt("protein_complex.pdb", chains=["A", "B"])

# Map all interactions
interactions = analyzer.map_interactions()

# Generate statistics
stats = analyzer.get_interaction_statistics()

# Find hotspot residues (highly interactive residues)
hotspots = []
for residue, count in list(stats['residue_frequencies'].items())[:5]:
    hotspots.append((residue, count))

print("Interface hotspot residues:")
for residue, count in hotspots:
    print(f"  - {residue}: {count} interactions")

# Analyze interaction types at the interface
print("\nInteraction composition at the interface:")
total = stats['total_interactions']
for interaction_type, count in stats['by_type'].items():
    if count > 0:
        percentage = (count / total) * 100
        print(f"  - {interaction_type}: {count} ({percentage:.1f}%)")

Drug Binding Site Analysis

# Analyze a protein-ligand complex
analyzer = PandaProt("protein_ligand.pdb", chains=["A", "L"])

# Map interactions with focus on drug binding
interactions = analyzer.map_interactions()

# Create a pharmacophore model based on interactions
pharmacophore_features = {
    'hydrogen_bond_donors': [],
    'hydrogen_bond_acceptors': [],
    'ionic_positive': [],
    'ionic_negative': [],
    'hydrophobic': [],
    'aromatic': []
}

# Extract pharmacophore features from interactions
for interaction_type, interactions_list in interactions.items():
    for interaction in interactions_list:
        # Focus on protein-ligand interactions
        if interaction_type == 'hydrogen_bonds':
            if 'donor_chain' in interaction and interaction['donor_chain'] == 'A':
                pharmacophore_features['hydrogen_bond_acceptors'].append(interaction['donor_residue'])
            elif 'acceptor_chain' in interaction and interaction['acceptor_chain'] == 'A':
                pharmacophore_features['hydrogen_bond_donors'].append(interaction['acceptor_residue'])
        
        elif interaction_type == 'ionic_interactions':
            if 'positive_chain' in interaction and interaction['positive_chain'] == 'A':
                pharmacophore_features['ionic_negative'].append(interaction['positive_residue'])
            elif 'negative_chain' in interaction and interaction['negative_chain'] == 'A':
                pharmacophore_features['ionic_positive'].append(interaction['negative_residue'])
        
        elif interaction_type == 'hydrophobic_interactions':
            if 'chain1' in interaction and interaction['chain1'] == 'A':
                pharmacophore_features['hydrophobic'].append(interaction['residue1'])
            elif 'chain2' in interaction and interaction['chain2'] == 'A':
                pharmacophore_features['hydrophobic'].append(interaction['residue2'])
        
        elif interaction_type in ['pi_stacking', 'pi_cation', 'cation_pi']:
            if 'aromatic_chain' in interaction and interaction['aromatic_chain'] == 'A':
                pharmacophore_features['aromatic'].append(interaction['aromatic_residue'])

print("Pharmacophore features for drug design:")
for feature_type, residues in pharmacophore_features.items():
    if residues:
        print(f"  - {feature_type}: {', '.join(set(residues))}")

Detailed Interaction Types

PandaProt detects and analyzes the following interaction types:

Standard Interactions

Hydrogen Bonds

• Definition: Non-covalent interaction between a hydrogen atom covalently bonded to an electronegative donor atom (N, O) and another electronegative acceptor atom
• Strength: 2-10 kcal/mol
• Distance Criteria: Donor-acceptor distance < 3.5Å
• Angle Criteria: Donor-H-acceptor angle > 120°

Ionic Interactions

• Definition: Electrostatic attraction between oppositely charged groups
• Strength: 10-20 kcal/mol
• Distance Criteria: < 6.0Å between charged groups
• Residues Involved: Positive (Arg, Lys, His) and negative (Asp, Glu)

Hydrophobic Interactions

• Definition: Clustering of non-polar side chains to exclude water
• Strength: 1-2 kcal/mol per methylene group
• Distance Criteria: < 5.0Å between carbon atoms
• Residues Involved: Ala, Val, Leu, Ile, Met, Phe, Trp, Pro, Tyr

Pi-Pi Stacking

• Definition: Interaction between aromatic rings
• Types: Parallel, T-shaped, offset stacked
• Strength: 2-3 kcal/mol
• Distance Criteria: < 7.0Å between ring centers
• Angle Criteria: Dependent on stacking type
• Residues Involved: Phe, Tyr, Trp, His

Pi-Cation Interactions

• Definition: Attraction between a cation and the face of an aromatic ring
• Strength: 3-5 kcal/mol
• Distance Criteria: < 6.0Å between cation and ring center
• Residues Involved: Cation (Arg, Lys) and aromatic (Phe, Tyr, Trp)

Salt Bridges

• Definition: Close-range ionic interaction with partial covalent character
• Strength: 10-20 kcal/mol
• Distance Criteria: < 4.0Å between charged groups
• Residues Involved: Acidic (Asp, Glu) and basic (Arg, Lys, His)

Enhanced Interactions

Cation-Pi Interactions

• Definition: Electrostatic attraction between a cation and π-electron system
• Strength: 2-5 kcal/mol
• Distance Criteria: < 6.0Å between cation and ring center
• Residues Involved: Cation (Arg, Lys, metal ions) and aromatic (Phe, Tyr, Trp)

CH-Pi Interactions

• Definition: Weak hydrogen bond between a CH group and an aromatic ring
• Strength: 0.5-1.0 kcal/mol
• Distance Criteria: < 4.0Å between CH and ring center
• Angle Criteria: CH vector pointing toward ring plane

Disulfide Bridges

• Definition: Covalent bond between sulfur atoms of cysteine residues
• Strength: 60-70 kcal/mol (covalent)
• Distance Criteria: 2.0-2.2Å between sulfur atoms
• Residues Involved: Cys

Sulfur-Aromatic Interactions

• Definition: Interaction between sulfur atoms and aromatic rings
• Strength: 1-2 kcal/mol
• Distance Criteria: < 5.5Å between sulfur and ring center
• Residues Involved: Sulfur (Met, Cys) and aromatic (Phe, Tyr, Trp)

Water-Mediated Interactions

• Definition: Hydrogen bonds bridged by water molecules
• Strength: Similar to regular hydrogen bonds
• Distance Criteria: < 3.5Å between polar atom and water
• Types: Water bridges, water networks

Metal-Coordinated Bonds

• Definition: Coordination between metal ions and electron-rich atoms
• Strength: 20-40 kcal/mol
• Distance Criteria: Depends on metal (typically 1.8-2.5Å)
• Coordination: Tetrahedral, octahedral, square planar
• Metals: Zn²⁺, Ca²⁺, Mg²⁺, Fe²⁺/³⁺, etc.

Halogen Bonds

• Definition: Interaction between halogen atom (Lewis acid) and Lewis base
• Strength: 1-5 kcal/mol
• Distance Criteria: < 4.0Å between halogen and acceptor
• Angle Criteria: C-X···Y angle close to 180°
• Atoms Involved: F, Cl, Br, I as donors; O, N, S as acceptors

Amide-Aromatic Interactions

• Definition: Interaction between amide groups and aromatic rings
• Strength: 1-3 kcal/mol
• Distance Criteria: < 4.5Å between amide and ring center
• Residues Involved: Amide (Asn, Gln, backbone) and aromatic (Phe, Tyr, Trp)

Van der Waals Interactions

• Definition: Weak non-specific attractive forces between atoms
• Strength: 0.1-1.0 kcal/mol per atom pair
• Distance Criteria: Sum of van der Waals radii + 40%
• Involves: All atom types

Amide-Amide Hydrogen Bonds

• Definition: Hydrogen bonds between amide groups
• Strength: Similar to regular hydrogen bonds
• Distance Criteria: < 3.5Å between amide groups
• Residues Involved: Asn, Gln, backbone amides

Technical Details

Distance Criteria

PandaProt uses carefully calibrated distance criteria for each interaction type:

Interaction Type	Default Distance Cutoff (Å)
Hydrogen Bonds	3.5
Ionic Interactions	6.0
Hydrophobic Interactions	5.0
Pi-Pi Stacking	7.0
Pi-Cation	6.0
Salt Bridges	4.0
Cation-Pi	6.0
CH-Pi	4.0
Disulfide Bridges	2.2
Sulfur-Aromatic	5.5
Water-Mediated	3.5 (per hydrogen bond)
Metal-Coordination	3.0
Halogen Bonds	4.0
Amide-Aromatic	4.5
Van der Waals	vdW radii sum × 1.4
Amide-Amide	3.5

These distance cutoffs can be customized using the distance_cutoff parameter.

Requirements

• Python 3.7+
• BioPython
• NumPy
• Pandas
• Matplotlib
• py3Dmol
• NetworkX

Citation

If you use PandaProt in your research, please cite:

Pritam Kumar Panda. (2025). 
A comprehensive Python application for mapping and visualizing molecular interactions at protein/nucleic acid interfaces and  tool for mapping protein-protein, protein-nucleic acid, and antigen-antibody interactions. GitHub repository https://github.com/pritampanda15/PandaProt

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.