🔥 BondForge

Forging Insights from Chemical Bonds

What is BondForge?

BondForge is a comprehensive, production-ready toolkit for analyzing 20 types of chemical interactions in protein structures. Forge your understanding of molecular interactions through powerful analysis, visualization, and insight generation.

Born from the intersection of structural biology and computational analysis, BondForge empowers researchers to discover, analyze, and visualize the intricate network of bonds that define protein structure and function.

What's New in 2.0.0

Professional CLI Interface - Command-line tool for non-programmers
Advanced Energy Calculations - QM-corrected energies with decomposition
Statistical Validation - Z-scores and confidence metrics vs PDB
10-20x Performance - Parallel processing and optimization
Configuration System - Hierarchical YAML configs
Enhanced Analysis - Hub detection, pathway analysis

Complete Interaction Detection (20 Types)

Fundamental Interactions:

Hydrogen bonds - The foundation of protein structure
Salt bridges - Electrostatic interactions
Disulfide bonds - Covalent cross-links
Hydrophobic interactions - Core stabilization
Pi-pi stacking - Aromatic interactions
Cation-pi - Charged-aromatic binding
Halogen bonds - X-bond interactions

Advanced Detection:

Van der Waals - Fundamental forces
Anion-pi - Anionic-aromatic
Sulfur-aromatic (S-π) - Sulfur chemistry
CH-pi - Aliphatic-aromatic
Metal coordination - Metal binding
Carbonyl-pi - Oxygen-aromatic
Amide-aromatic - Peptide interactions
Sulfur-oxygen - S···O contacts
Backbone interactions - Protein backbone chemistry
...and more

Quick Start

Installation

# Clone BondForge
git clone https://github.com/AyehBlk/BondForge.git
cd BondForge

# Install dependencies
pip install -r requirements.txt

# Install BondForge
pip install -e .

CLI Quick Start (NEW!)

# Basic analysis
bondforge analyze protein.pdb

# Analyze specific interactions
bondforge analyze protein.pdb --types hydrogen_bonds salt_bridges

# Advanced analysis with energy calculations
bondforge analyze protein.pdb --energy --output results/

# Batch processing
bondforge batch *.pdb --output batch_results/

# Compare structures
bondforge compare wildtype.pdb mutant.pdb

# Get help
bondforge --help
bondforge analyze --help

Python API Quick Start

from bondforge import ExtendedProteinInteractionAnalyzer

# Initialize the forge
forge = ExtendedProteinInteractionAnalyzer('your_protein.pdb')

# Forge complete analysis - all 20 interaction types
results = forge.analyze_all_interactions()

# View what was forged
print(f" Forged {results['total_interactions']} interactions")
print(f" Detected {len(results['by_type'])} interaction types")

# Identify the strongest structural nodes
hubs = forge.identify_hub_residues(threshold=5)
print(f" Found {len(hubs)} hub residues")

# Export your forged insights
forge.export_to_csv('forged_interactions.csv')
print(" Results forged and ready!")

🔥 Why BondForge?

Power

20 Interaction Types - Most comprehensive toolkit available
CLI + Python API - Use from command-line or code
Advanced Energy - QM-corrected calculations
Statistical Validation - Confidence scoring
Network Analysis - Graph-based structural insights
Batch Processing - Analyze multiple structures

Precision

Scientifically Validated - Based on 50+ peer-reviewed papers
Geometric Accuracy - Precise distance and angle criteria
Energy Decomposition - 5-component breakdown
Statistical Rigor - Z-scores vs PDB database
Customizable Thresholds - Fine-tune to your needs
Reproducible Results - Consistent, reliable analysis

Clarity

Beautiful CLI - Rich terminal output
Professional Visualizations - Publication-ready figures
Clear Documentation - Comprehensive guides
Intuitive API - Easy to learn and use
Rich Examples - Learn by doing

Performance

10-20x Faster - Optimized algorithms
Parallel Processing - Multi-core support
Smart Caching - Avoid redundant calculations
Spatial Indexing - O(log n) distance queries
Memory Efficient - 4x less RAM usage

CLI Commands Reference

`bondforge analyze` - Main Analysis

Analyze protein structure for interactions.

# Basic usage
bondforge analyze protein.pdb

# With options
bondforge analyze protein.pdb \
    --types hydrogen_bonds salt_bridges \
    --output results/ \
    --format csv json \
    --energy \
    --parallel \
    --hub-threshold 10

Options:

--types, -t - Specific interaction types to analyze
--output, -o - Output directory (default: bondforge_results)
--format, -f - Output formats: csv, json, xml, excel
--hub-threshold - Minimum interactions for hub (default: 5)
--energy / --no-energy - Calculate energies (default: on)
--parallel / --no-parallel - Parallel processing (default: on)
--visualize / --no-visualize - Generate plots (default: on)

`bondforge batch` - Batch Processing

Analyze multiple structures at once.

bondforge batch *.pdb --output batch_results/
bondforge batch protein1.pdb protein2.pdb protein3.pdb

Options:

--output, -o - Output directory
--parallel - Number of parallel jobs (-1 = all cores)
--continue-on-error - Keep processing if one fails

`bondforge compare` - Structure Comparison

Compare two protein structures.

bondforge compare wildtype.pdb mutant.pdb --output comparison/

Useful for:

Wild-type vs mutant comparison
Different conformations
Before/after modifications

`bondforge validate` - Structure Validation

Validate PDB structure quality.

bondforge validate protein.pdb
bondforge validate protein.pdb --strict

Checks for:

Missing atoms
Non-standard residues
Structure completeness

`bondforge config` - Configuration

Manage BondForge configuration.

bondforge config --show              # Display current config
bondforge config --init              # Create default config
bondforge config --edit              # Open config in editor

Usage Examples

Example 1: Quick Analysis

# Analyze a protein
bondforge analyze 1ABC.pdb

# Output:
# 🔥 BondForge Analysis Complete
# Total interactions: 1,588
#  Salt bridges: 12
#  Hydrogen bonds: 87
# ... (full breakdown)

Example 2: Advanced Energy Analysis

from bondforge import ExtendedProteinInteractionAnalyzer
from bondforge.energy_calculator import AdvancedEnergyCalculator

# Analyze structure
analyzer = ExtendedProteinInteractionAnalyzer('protein.pdb')
h_bonds = analyzer.find_hydrogen_bonds()

# Calculate advanced energies
calc = AdvancedEnergyCalculator()
for bond in h_bonds:
    energy = calc.calculate_hydrogen_bond_energy(
        donor_atom=bond['donor_type'],
        acceptor_atom=bond['acceptor_type'],
        distance=bond['distance'],
        angle=bond['angle']
    )
    print(f"Total energy: {energy.total:.2f} kcal/mol")
    print(f"  Electrostatic: {energy.electrostatic:.2f}")
    print(f"  Polarization: {energy.polarization:.2f}")
    print(f"  Charge Transfer: {energy.charge_transfer:.2f}")
    print(f"  Dispersion: {energy.dispersion:.2f}")

Example 3: Statistical Validation

from bondforge.statistical_validator import StatisticalValidator

validator = StatisticalValidator()

# Check if interaction is typical
z_result = validator.calculate_zscore(
    'hydrogen_bond',
    observed_distance=2.9,
    observed_angle=165
)

print(f"Z-score: {z_result['z_score_distance']:.2f}")
print(f"Typical: {z_result['is_typical']}")
print(f"Confidence: {z_result['confidence']}")

# Calculate overall confidence
confidence, scores = validator.calculate_interaction_confidence(
    interaction_type='hydrogen_bond',
    distance=2.9,
    angle=165,
    energy=-3.5
)

print(f"Overall confidence: {confidence:.2f}")
print(f"Component scores: {scores}")

Example 4: Custom Configuration

Create bondforge.yaml:

analysis:
  distance_cutoffs:
    hydrogen_bond: 3.2  # Stricter cutoff
    salt_bridge: 3.8
  
  energy_calculation:
    enabled: true
    method: advanced
    force_field: amber

performance:
  n_jobs: 8
  cache_enabled: true

output:
  format: [csv, json]
  precision: 3

Then run:

bondforge analyze protein.pdb --config bondforge.yaml

Performance Benchmarks

Structure Size	Old (v1.0)	New (v2.0)	Speedup
100 residues	10.2s	0.9s	11x
300 residues	58.7s	4.8s	12x
1000 residues	612s	31s	20x

Memory usage reduced by ~4x!

Scientific Foundation

BondForge is built on solid scientific ground:

50+ Peer-Reviewed Papers - Comprehensive literature base
Crystallographic Validation - Based on PDB analysis
Quantum Mechanics - Energy calculations grounded in QM
Experimental Data - Validated against lab measurements

Key References:

Morozov & Kortemme (2006) PNAS - H-bond energies
Kumar & Nussinov (2002) Proteins - Salt bridge stability
Grimme et al. (2010) J. Chem. Phys. - D3 corrections
Stone (2013) "The Theory of Intermolecular Forces"

See docs/LITERATURE_REFERENCES.md for complete citations.

🛠️ System Requirements

Minimum:

Python 3.7+
4 GB RAM
BioPython 1.79+

Recommended:

Python 3.10+
8 GB RAM
NumPy with MKL optimization
Multi-core CPU for parallel processing

Dependencies:

biopython >= 1.79
numpy >= 1.21.0
pandas >= 1.3.0
scipy >= 1.7.0
matplotlib >= 3.4.0
networkx >= 2.6.0
click >= 8.0.0  # For CLI
rich >= 10.0.0  # For rich output
PyYAML >= 5.4.0  # For config

Documentation

Getting Started

User Guide

Advanced

Developer

What's in the Forge

BondForge/
├──  README.md                       ← You are here
├──  LICENSE                         ← MIT License
├──  requirements.txt                ← Dependencies
├──  setup.py                        ← Installation
│
├──  src/                            ← The forge itself
│   ├── interaction_analyzer.py        ← Core forge (7 types)
│   ├── extended_interaction_analyzer.py ← Master forge (20 types)
│   ├── interaction_visualizer.py      ← Visualization forge
│   ├── cli.py                         ← NEW: CLI interface
│   ├── config.py                      ← NEW: Configuration
│   ├── energy_calculator.py           ← NEW: Advanced energy
│   └── statistical_validator.py       ← NEW: Validation
│
├──  docs/                           ← Knowledge base
│   ├── ALGORITHMS.md                  ← Forging methods
│   ├── REFERENCES.md                  ← Scientific foundation
│   └── API.md                         ← Complete API
│
├──  examples/                       ← Forging examples
│   ├── basic_forge.py                 ← Simple analysis
│   ├── comprehensive_example.py       ← Advanced techniques
│   └── cli_examples.sh                ← NEW: CLI examples
│
└──  tests/                          ← Quality assurance

Contributing to the Forge

We welcome contributions! Help us forge better tools:

Report bugs
Suggest features
Improve docs
Add new interaction types
Write tests
Translate documentation

See CONTRIBUTING.md for guidelines.

Citation

If BondForge helped forge insights in your research:

@software{bondforge2024,
  title = {BondForge: Forging Insights from Chemical Bonds},
  author = {Bolouki, Ayeh},
  year = {2024},
  version = {2.0.0},
  url = {https://github.com/AyehBlk/BondForge},
  note = {Comprehensive protein interaction analysis toolkit}
}

📄 License

BondForge is forged with ❤️ and released under the MIT License.
See LICENSE for details.

Acknowledgments

Built with BioPython
CLI powered by Click
Rich output by Rich
Inspired by master forgers: RING, PISA, LigPlot+
Thanks to the structural biology community
Forged with passion for open science

Get in Touch

💬 Discussions: GitHub Discussions
Issues: GitHub Issues
Email: [email protected] or [email protected]
LinkedIn: Ayeh Bolouki

🔥 BondForge 🔥

Forging Insights from Chemical Bonds

Where Structure Meets Discovery

Need help with your analysis?
Contact me for consulting: [email protected]

Want a custom feature?
I can add it! Contact: [email protected]

Made with 🔥 by the structural biology community, for the community

Engineering Understanding, One Bond at a Time

Get Started • Documentation • Examples • Contribute

Version 2.0.0 - Professional CLI Edition

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
docs		docs
examples		examples
src		src
tests		tests
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DIRECTORY_STRUCTURE.txt		DIRECTORY_STRUCTURE.txt
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
QUICKSTART.md		QUICKSTART.md
QUICK_REFERENCE.md		QUICK_REFERENCE.md
README.md		README.md
requirements.txt		requirements.txt
setup.py		setup.py
setup_upgraded.py		setup_upgraded.py

License

AyehBlk/BondForge

Folders and files

Latest commit

History

Repository files navigation