BackBonus

Advanced mol2 atom correspondence tool with cross-type-system Support

Overview

BackBonus is a Python tool for determining atom-wise correspondence between molecular structures in mol2 format. It attempts to match molecules even when they use different atom type systems (currently: SYBYL, AMBER, GAFF, GAFF2).

Key Features

• Cross-type-system matching: Maps between SYBYL, AMBER, GAFF, and GAFF2 atom types
• Automatic bond detection: Intelligently detects bonds based on atomic distances when not present in input files
• Multiple matching strategies: From exact matching to flexible element-based correspondence
• Rich reporting: Multiple output formats (Console, JSON, HTML, CSV) with detailed statistics
• Molecular validation: Validates bond lengths, valences, and molecular structure integrity
• Atom renaming: Automatically rename atoms in target molecules based on template correspondence

Installation

Using pip (recommended)

pip install backbonus

From Source

git clone https://github.com/MicheleBonus/backbonus.git
cd backbonus
pip install -e .

Development Installation

git clone https://github.com/MicheleBonus/backbonus.git
cd backbonus
pip install -e ".[dev]"

Quick Start

Command Line Interface

Basic Usage

# Simple correspondence finding
backbonus -t template.mol2 -T target.mol2

# With atom renaming
backbonus -t template.mol2 -T target.mol2 --rename -o renamed.mol2

# Cross-system matching (GAFF to SYBYL)
backbonus -t template_gaff.mol2 -T target_sybyl.mol2 --rename

Advanced Options

# Multiple output formats with bond detection
backbonus -t ref.mol2 -T query.mol2 -f console -f html -f json -b

# Using specific matching strategies
backbonus -t ref.mol2 -T query.mol2 -s cross -s relaxed -s element

# Specify atom type systems explicitly
backbonus -t template.mol2 -T target.mol2 --template-type sybyl --target-type gaff2

# Verbose output for debugging
backbonus -t ref.mol2 -T query.mol2 -vv

Python API

from backbonus import Mol2Parser, AtomCorrespondence, AtomTypeMapper

# Parse molecules
template_parser = Mol2Parser("template.mol2", detect_bonds=True)
template = template_parser.parse()

target_parser = Mol2Parser("target.mol2", detect_bonds=True)
target = target_parser.parse()

# Find correspondence
type_mapper = AtomTypeMapper()
correspondence = AtomCorrespondence(template, target, type_mapper)
result = correspondence.find_correspondence()

# Access results
print(f"Match: {result.match_percentage:.1f}%")
print(f"Strategy: {result.strategy_used.value}")
for target_id, template_id in result.mapping.items():
    print(f"Atom {target_id} -> {template_id}")

How It Works

Matching Process

BackBonus uses a graph-based approach to find atom correspondence:

1. Molecular graph construction: Converts mol2 structures into NetworkX graphs
2. Type system detection: Automatically identifies the atom type system used
3. Multi-strategy matching: Attempts various matching strategies in order:
   • Exact: Perfect match of atom types and bond orders
   • Cross-system: Maps between different type systems using comprehensive conversion tables
   • Relaxed: Matches based on element and connectivity
   • Element-only: Matches based solely on element types
   • Subgraph: Finds partial matches for incomplete correspondences

Atom Type Mapping

BackBonus includes comprehensive atom type mapping data derived from AmberTools/Antechamber:

• SYBYL: Tripos Sybyl atom types (e.g., C.3, N.pl3, O.2)
• AMBER: Amber force field types (e.g., CT, CA, N3)
• GAFF: General Amber Force Field types (e.g., c3, ca, n3)
• GAFF2: Updated GAFF types with improved parameters

The mapping system handles:

• Direct type conversions (e.g., C.3 → c3)
• Aromatic type recognition (e.g., C.ar → ca)
• Special atom types (e.g., N.pl3 → n)
• Halogen and metal atom types

Bond Detection Algorithm

When bonds are not present or need verification:

1. Distance Calculation: Computes distances between all atom pairs
2. Covalent Radii Check: Uses elemental covalent radii with tolerance
3. Bond Order Assignment: Determines single/double/triple/aromatic bonds
4. Validation: Checks valences and bond lengths for chemical validity

Configuration

Configuration File (YAML)

# config.yaml
matching:
  strategies: [cross, relaxed, element]
  timeout: 60

bond_detection:
  tolerance: 0.45
  max_bond_length: 3.0

output:
  formats: [console, json]
  include_charges: true

Use with: backbonus -t template.mol2 -T target.mol2 -c config.yaml

Output Formats

Console Output

Rich formatted output with colored tables and progress indicators

JSON Output

Structured data with complete mapping information:

{
  "summary": {
    "template_file": "template.mol2",
    "target_file": "target.mol2",
    "match_percentage": 95.2,
    "strategy": "cross"
  },
  "correspondence": [...]
}

HTML Report

Interactive web page with visualizations and statistics

CSV Export

Tabular format for analysis in spreadsheet applications

Testing

Run the test suite:

# Basic tests
pytest

# With coverage
pytest --cov=backbonus

# Specific test file
pytest tests/test_correspondence.py -v

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Citation

If you use BackBonus in your research, please cite:

@software{backbonus2025,
  author = {Bonus, Michele},
  title = {BackBonus: Advanced Mol2 Atom Correspondence Tool},
  year = {2025},
  url = {https://github.com/MicheleBonus/backbonus}
}

License

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

Acknowledgments

• Atom type definitions and mapping data derived from AmberTools/Antechamber
• Graph algorithms powered by NetworkX
• Beautiful terminal output via Rich

Contact

Michele Bonus - Michele.Bonus@hhu.de

Project Link: https://github.com/MicheleBonus/backbonus

Roadmap

• GUI interface for visual correspondence inspection
• Support for other molecular file formats
• Machine learning-based matching for difficult cases
• Integration with popular molecular visualization tools
• Batch processing capabilities