https://github.com/abhishektiwari/hbat
HBAT 2: A Python Package to analyse Hydrogen Bonds and Other Non-covalent Interactions in Macromolecular Structures
https://github.com/abhishektiwari/hbat
bioinformatics bioinformatics-tool chemistry computer-aided-drug-design crystallography drug-discovery halogen-bonds hydrogen-bonds molecular-dynamics molecular-dynamics-simulation molecular-interactions noncovalent-interactions pdb pi-interaction protein-data-bank protein-dna-interactions protein-ligand-interactions protein-protein-interaction structural-bioinformatics structural-biology
Last synced: 6 days ago
JSON representation
HBAT 2: A Python Package to analyse Hydrogen Bonds and Other Non-covalent Interactions in Macromolecular Structures
- Host: GitHub
- URL: https://github.com/abhishektiwari/hbat
- Owner: abhishektiwari
- License: mit
- Created: 2025-06-30T00:29:59.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-06-13T02:00:10.000Z (6 days ago)
- Last Synced: 2026-06-13T02:15:14.411Z (6 days ago)
- Topics: bioinformatics, bioinformatics-tool, chemistry, computer-aided-drug-design, crystallography, drug-discovery, halogen-bonds, hydrogen-bonds, molecular-dynamics, molecular-dynamics-simulation, molecular-interactions, noncovalent-interactions, pdb, pi-interaction, protein-data-bank, protein-dna-interactions, protein-ligand-interactions, protein-protein-interaction, structural-bioinformatics, structural-biology
- Language: Python
- Homepage: https://hbat.abhishek-tiwari.com
- Size: 5.82 MB
- Stars: 10
- Watchers: 0
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
# HBAT 2 (Hydrogen Bond Analysis Tool 2)
A Python package to automate the analysis of potential hydrogen bonds and similar type of weak interactions in macromolecular structures from Protein Data Bank (PDB). HBAT 2 supports both `.pdb` and `.cif` (mmCIF) file formats and uses a geometric approach to identify molecular interactions by analyzing distance and angular criteria.
**Supported Interaction Types:**
- **Hydrogen Bonds**: Classical `N-H···O`, `O-H···O`, and weak `C-H···O` interactions
- **Halogen Bonds**: `C-X···A` interactions (`X = Cl, Br, I`)
- **π Interactions**: X-H···π and `C-X···π` interactions with aromatic rings (`Phe`, `Tyr`, `Trp`, `His`, etc.)
- **π-π Stacking**: Aromatic ring-ring interactions (parallel, T-shaped, offset)
- **Carbonyl Interactions**: `n→π*` interactions between carbonyl groups
- **n-π Interactions**: Lone pair interactions with aromatic `π` systems
- **Water Bridges**: Water-mediated hydrogen bond networks connecting protein/ligand residues
- **Ligand Interactions**: Comprehensive detection of all interaction types between ligands and protein/nucleic acid residues
> **HBAT 2 Web Interface** is Live! Try it out at [hbat-web.abhishek-tiwari.com](https://hbat-web.abhishek-tiwari.com)
[](https://codecov.io/gh/abhishektiwari/hbat)
[](https://socket.dev/pypi/package/hbat/overview/2.2.11/py3-none-any-whl)
[](https://www.codefactor.io/repository/github/abhishektiwari/hbat/overview/main)
[](https://doi.org/10.3233/ISI-2007-00337)
[](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=Mb7eYKYAAAAJ&citation_for_view=Mb7eYKYAAAAJ:u-x6o8ySG0sC)
[](https://doi.org/10.48550/arXiv.2602.17712)
[](https://doi.org/10.26434/chemrxiv.15000141/v1)
[](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=Mb7eYKYAAAAJ&citation_for_view=Mb7eYKYAAAAJ:3bvyWxjaHKcC)
**HBAT Desktop (Mac, Windows, Linux):**
**HBAT Web:** Try it out at [hbat-web.abhishek-tiwari.com](https://hbat-web.abhishek-tiwari.com)
**Visualizing interactions with HBAT Web using D3MOl and PyMOL (PDB Entry 6RSA):**
**Cooperativity chain detection and visualization (PDB Entry 6RSA):**
## Background
HBAT 2 is a modern Python re-implementation of the original Perl-based tool developed by [Abhishek Tiwari](https://www.abhishek-tiwari.com) and Sunil Kumar Panigrahi. HBAT v1 can still be downloaded from [SourceForge](https://sourceforge.net/projects/hbat/files/HBAT/) however Perl version is not maintained anymore.
## Highlights of HBAT 2
- Detect and analyze potential hydrogen bonds, halogen bonds, π interactions, π-π stacking, carbonyl interactions, n-π interactions, water bridges, and ligand interactions
- Automated PDB fixing with OpenBabel and PDBFixer integration
- Support graphical (tkinter), command-line, and programming API interfaces
- Use graphical interfaces for interactive analysis, CLI/API for batch processing and automation
- Ligand interaction analysis with residue-specific visualization and filtering
- Water bridge detection and analysis with bridge path visualization
- Hydrogen bond network (potential cooperativity/anticooperativity chains and water-mediated hydrogen bond networks) visualization using NetworkX/matplotlib and GraphViz
- Export hydrogen bond network visualizations to PNG, SVG, PDF formats
- 3D visualization of interactions using 3Dmol.js in Jupyter notebooks and HBAT web interface
- Export and visualize interactions in PyMOL from HBAT web interface
- Built-in presets for different structure types (high-resolution, NMR, membrane proteins, etc.)
- Customizable distance cutoffs, angle thresholds, and analysis modes.
- Multiple Output Formats: Text, CSV, and JSON export options
- Optimized algorithms for efficient analysis of large structures
- Cross-Platform: Works on Windows, macOS, and Linux.
Please review [HBAT documentation](https://hbat.abhishek-tiwari.com/) for more details.
## Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install hbat
```
Run HBAT Command-Line Interface (CLI) using `hbat` or launch HBAT GUI using `hbat-gui`.
### Option 2: Install from Source
```bash
git clone https://github.com/abhishektiwari/hbat.git
cd hbat
pip install -e .
```
Alternatively,
```bash
pip install git+https://github.com/abhishektiwari/hbat.git
```
Run HBAT Command-Line Interface (CLI) using `hbat` or launch HBAT GUI using `hbat-gui`.
### Option 3: Install from Conda
```
conda install -c hbat hbat
```
### Requirements
#### System Requirements
- Python: 3.9 or higher
- tkinter: tkinter is included with Python standard library on most systems. However, on Mac install Python and tkinter using `brew`.
```
brew install python python3-tk
```
- GraphViz (Optional): Required for advanced cooperativity chain visualization with high-quality graph rendering. HBAT will automatically fall back to NetworkX/matplotlib visualization if GraphViz is not available.
Install GraphViz:
On Ubuntu/Debian:
```bash
sudo apt-get update
sudo apt-get install graphviz
```
On macOS (using Homebrew):
```bash
brew install graphviz
```
On Windows:
- Download and install from [GraphViz official website](https://graphviz.org/download/)
- Or using Chocolatey: `choco install graphviz`
- Or using conda: `conda install -c conda-forge graphviz`
> Note: After installing GraphViz, restart your terminal/command prompt before running HBAT to ensure the GraphViz executables are available in your PATH.
## Usage
### Graphical Interface
Launch the GUI application:
```bash
hbat-gui
```
The GUI provides,
- File browser for loading PDB files
- Parameter configuration panels
- Tabbed results display
- Export and visualization options
### Command-Line Interface
Basic usage:
```bash
hbat input.pdb
hbat input.cif
```
#### Output Format Options
HBAT supports multiple output formats:
```bash
# No output flag - displays results to console
hbat input.pdb
# Display results to console
# Single file outputs (format auto-detected from extension)
hbat input.pdb -o results.txt # Text format (human-readable summary + details)
hbat input.pdb -o results.json # JSON format (single file with all interactions)
# Multiple file outputs (separate files per interaction type)
hbat input.pdb --csv results # Creates results_h_bonds.csv, results_x_bonds.csv, etc.
hbat input.pdb --json results # Creates results_h_bonds.json, results_x_bonds.json, etc.
```
With custom parameters:
```bash
hbat input.pdb -o results.txt --hb-distance 3.0 --mode inter
```
Interaction inclusion modes:
| Mode | Inter-residue | Intra-residue |
|---|---:|---:|
| `inter` | Yes | No |
| `all` | Yes | Yes |
> **Breaking change:** The previous `local` and `complete` mode values are no
> longer valid. Replace `local` with `inter` and `complete` with `all`.
#### List Available Presets
```bash
hbat --list-presets
```
#### Use a specific preset
```bash
hbat protein.pdb --preset high_resolution
hbat membrane_protein.pdb --preset membrane_proteins
```
#### Use preset with custom overrides
```bash
hbat protein.pdb --preset drug_design_strict --hb-distance 3.0 --verbose
```
#### CLI Options
```
positional arguments:
input Input PDB file
optional arguments:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
Output file (format auto-detected from extension: .txt, .json)
--json JSON Export to multiple JSON files (base name for files)
--csv CSV Export to multiple CSV files (base name for files)
Preset Options:
--preset PRESET Load parameters from preset file (.hbat or .json)
--list-presets List available example presets and exit
Analysis Parameters:
Hydrogen Bond Parameters:
--hb-distance HB_DISTANCE
Hydrogen bond H...A distance cutoff in Å (default: 2.5)
--hb-angle HB_ANGLE Hydrogen bond D-H...A angle cutoff in degrees (default: 120)
--da-distance DA_DISTANCE
Donor-acceptor distance cutoff in Å (default: 3.5)
Halogen Bond Parameters:
--xb-distance XB_DISTANCE
Halogen bond X...A distance cutoff in Å (default: 3.9)
--xb-angle XB_ANGLE Halogen bond C-X...A angle cutoff in degrees (default: 150)
π Interaction Parameters:
--pi-distance PI_DISTANCE
π interaction H...π distance cutoff in Å (default: 3.5)
--pi-angle PI_ANGLE π interaction D-H...π angle cutoff in degrees (default: 110)
π-π Stacking Parameters:
--pi-pi-distance PI_PI_DISTANCE
π-π centroid-to-centroid distance cutoff in Å (default: 3.8)
--pi-pi-parallel-angle PI_PI_PARALLEL_ANGLE
Maximum angle for parallel π-π stacking in degrees (default: 30.0)
--pi-pi-tshaped-angle-min PI_PI_TSHAPED_ANGLE_MIN
Minimum angle for T-shaped π-π stacking in degrees (default: 60.0)
--pi-pi-tshaped-angle-max PI_PI_TSHAPED_ANGLE_MAX
Maximum angle for T-shaped π-π stacking in degrees (default: 90.0)
--pi-pi-offset PI_PI_OFFSET
Maximum lateral offset for parallel π-π stacking in Å (default: 2.0)
Carbonyl Interaction Parameters (n→π*):
--carbonyl-distance CARBONYL_DISTANCE
Carbonyl O···C distance cutoff in Å (default: 3.2)
--carbonyl-angle-min CARBONYL_ANGLE_MIN
Minimum O···C=O angle for carbonyl interactions in degrees (default: 95.0)
--carbonyl-angle-max CARBONYL_ANGLE_MAX
Maximum O···C=O angle for carbonyl interactions in degrees (default: 125.0)
n→π* Interaction Parameters:
--n-pi-distance N_PI_DISTANCE
Lone pair to π center distance cutoff in Å (default: 3.6)
--n-pi-sulfur-distance N_PI_SULFUR_DISTANCE
Sulfur-specific distance cutoff in Å (default: 4.0)
--n-pi-angle-min N_PI_ANGLE_MIN
Minimum angle to π plane in degrees (default: 0.0)
--n-pi-angle-max N_PI_ANGLE_MAX
Maximum angle to π plane in degrees (default: 45.0)
General Parameters:
--covalent-factor COVALENT_FACTOR
Covalent bond detection factor (default: 0.85)
--mode {inter,all}
Interaction inclusion mode: inter includes interactions
between different residues only; all also includes
intra-residue interactions
Output Control:
--verbose, -v Verbose output with detailed progress
--quiet, -q Quiet mode with minimal output
--summary-only Output summary statistics only
Analysis Filters:
--no-hydrogen-bonds Skip hydrogen bond analysis
--no-halogen-bonds Skip halogen bond analysis
--no-pi-interactions Skip π interaction analysis
--no-pi-pi-stacking Skip π-π stacking analysis
--no-carbonyl-interactions
Skip carbonyl n→π* interaction analysis
--no-n-pi-interactions
Skip n→π* interaction analysis
```
## Example Notebooks
Interactive Jupyter notebooks demonstrating HBAT usage with 3D visualizations using Py3DMol.
| Notebook | Description | Colab |
|----------|-------------|-------|
| [01_analyze_6rsa_with_visualization.ipynb](notebooks/01_analyze_6rsa_with_visualization.ipynb) | Hydrogen bond analysis of 6RSA (Ribonuclease A) with py3Dmol visualization | [](https://colab.research.google.com/github/abhishektiwari/hbat/blob/main/notebooks/01_analyze_6rsa_with_visualization.ipynb) |
| [02_halogen_bonds_4x21.ipynb](notebooks/02_halogen_bonds_4x21.ipynb) | Halogen bond detection and visualization in 4X21 structure | [](https://colab.research.google.com/github/abhishektiwari/hbat/blob/main/notebooks/02_halogen_bonds_4x21.ipynb) |
| [03_pdbfixer_vs_openbabel_comparison.ipynb](notebooks/03_pdbfixer_vs_openbabel_comparison.ipynb) | Comparing PDBFixer vs OpenBabel for hydrogen addition | [](https://colab.research.google.com/github/abhishektiwari/hbat/blob/main/notebooks/03_pdbfixer_vs_openbabel_comparison.ipynb) |
See the [notebooks directory](notebooks/) for more details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Cite HBAT and HBAT 2
If you use HBAT 2 in your research, please cite:
[](https://doi.org/10.48550/arXiv.2602.17712)
```
@article{tiwari_2026_hbat_arxiv,
author = {Tiwari, Abhishek},
title = {HBAT 2: A Python Package to analyse Hydrogen Bonds and Other Non-covalent Interactions in Macromolecular Structures},
year = 2026,
publisher = {arXiv},
doi = {10.48550/arXiv.2602.17712},
url = {https://arxiv.org/abs/2602.17712},
}
```
or
[](https://doi.org/10.26434/chemrxiv.15000141/v1)
```
@article{tiwari_2026_hbat_chemrxiv,
author = {Abhishek Tiwari },
title = {HBAT 2: A Python Package to Analyse Hydrogen Bonds and Other Non-covalent Interactions in Macromolecular Structures},
publisher = {ChemRxiv},
year = {2026},
doi = {10.26434/chemrxiv.15000141/v1},
URL = {https://chemrxiv.org/doi/abs/10.26434/chemrxiv.15000141/v1},
eprint = {https://chemrxiv.org/doi/pdf/10.26434/chemrxiv.15000141/v1},
}
```
If you use HBAT 1.0 or 1.1 in your research, please cite:
[](https://doi.org/10.3233/ISI-2007-00337)
```
@article{tiwari2007hbat,
author = {Tiwari, Abhishek and Panigrahi, Sunil Kumar},
doi = {10.3233/ISI-2007-00337},
journal = {In Silico Biology},
month = dec,
number = {6},
title = {{HBAT: A Complete Package for Analysing Strong and Weak Hydrogen Bonds in Macromolecular Crystal Structures}},
volume = {7},
year = {2007}
}
```
## Contributing
See our [contributing guide](CONTRIBUTING.md) and [development guide](https://hbat.abhishek-tiwari.com/development). At a high-level,
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request