hbat

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 11 Open GitHub ↗

HBAT 2: A Python Package to analyse Hydrogen Bonds and Other Non-covalent Interactions in Macromolecular Structures https://hbat-web.abhishek-tiwari.com

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![HBAT](https://github.com/abhishektiwari/hbat/raw/main/hbat.svg)

# 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)

![GitHub Release](https://img.shields.io/github/v/release/abhishektiwari/hbat)
![GitHub Actions Test Workflow Status](https://img.shields.io/github/actions/workflow/status/abhishektiwari/hbat/test.yml?label=tests)
![PyPI - Version](https://img.shields.io/pypi/v/hbat)
![Python Wheels](https://img.shields.io/pypi/wheel/hbat)
![Python Versions](https://img.shields.io/pypi/pyversions/hbat?logo=python&logoColor=white)
![GitHub last commit](https://img.shields.io/github/last-commit/abhishektiwari/hbat)
![PyPI - Status](https://img.shields.io/pypi/status/hbat)
![Conda Version](https://img.shields.io/conda/v/hbat/hbat)
![License](https://img.shields.io/github/license/abhishektiwari/hbat)
![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/abhishektiwari/hbat/total?label=GitHub%20Downloads)
![SourceForge Downloads](https://img.shields.io/sourceforge/dt/hbat?label=SourceForge%20Downloads)
![PyPI Downloads](https://img.shields.io/pepy/dt/hbat?label=PyPI%20Downloads)
[![codecov](https://codecov.io/gh/abhishektiwari/hbat/graph/badge.svg?token=QSKYLB3M1V)](https://codecov.io/gh/abhishektiwari/hbat)
[![Socket](https://socket.dev/api/badge/pypi/package/hbat/2.2.11?artifact_id=py3-none-any-whl)](https://socket.dev/pypi/package/hbat/overview/2.2.11/py3-none-any-whl)
[![CodeFactor](https://www.codefactor.io/repository/github/abhishektiwari/hbat/badge/main)](https://www.codefactor.io/repository/github/abhishektiwari/hbat/overview/main)
[![DOI HBAT](https://img.shields.io/badge/10.3233%2FISI-2007-00337?logo=doi&label=10.3233%2FISI-2007-00337&link=https%3A%2F%2Fdoi.org%2F10.3233%2FISI-2007-00337)](https://doi.org/10.3233/ISI-2007-00337)
[![Google Scholar Citation](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.juleskreuer.eu%2Fcitation-badge.php%3Fshield%26doi%3D10.3233%2FISI-2007-00337&link=https%3A%2F%2Fscholar.google.com%2Fcitations%3Fview_op%3Dview_citation%26hl%3Den%26user%3DMb7eYKYAAAAJ%26citation_for_view%3DMb7eYKYAAAAJ%3Au-x6o8ySG0sC)](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=Mb7eYKYAAAAJ&citation_for_view=Mb7eYKYAAAAJ:u-x6o8ySG0sC)
[![arXiv](https://img.shields.io/badge/arXiv-2602.17712-b31b1b.svg)](https://doi.org/10.48550/arXiv.2602.17712)
[![Chemrxiv](https://img.shields.io/badge/chemrxiv-15000141--v1-green)](https://doi.org/10.26434/chemrxiv.15000141/v1)
[![Google Scholar Citation](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.juleskreuer.eu%2Fcitation-badge.php%3Fshield%26doi%3D10.26434%2Fchemrxiv.15000141%2Fv1&link=https%3A%2F%2Fscholar.google.com%2Fcitations%3Fview_op%3Dview_citation%26hl%3Den%26user%3DMb7eYKYAAAAJ%26citation_for_view%3DMb7eYKYAAAAJ%3A3bvyWxjaHKcC)](https://scholar.google.com/citations?view_op=view_citation&hl=en&user=Mb7eYKYAAAAJ&citation_for_view=Mb7eYKYAAAAJ:3bvyWxjaHKcC)

**HBAT Desktop (Mac, Windows, Linux):**
![HBAT Desktop](https://static.abhishek-tiwari.com/hbat/hbat-window-v3.png)

**HBAT Web:** Try it out at [hbat-web.abhishek-tiwari.com](https://hbat-web.abhishek-tiwari.com)

![HBAT Web](https://static.abhishek-tiwari.com/hbat/hbat-2-web-v2.png)

**Visualizing Water Bridge with HBAT Web using PyMOL (PDB Entry 6RSA):**
![Water Bridge in PDB Entry 6RSA](https://static.abhishek-tiwari.com/hbat/6rsa_A_ARG_10_to_A_ASP_38_pymol.png)

**Visualizing interactions with HBAT Web using D3MOl (PDB Entry 6RSA):**

![Pi Interaction in PDB Entry 6RSA](https://static.abhishek-tiwari.com/hbat/6rsa_A_MET_29_to_A_PHE_46_pi.png)

**Visualizing Ligand Interactions in 2D using HBAT Web LigPlots (PDB Entry 2IZF)** 
![Ligand Interaction in 2IZF](https://static.abhishek-tiwari.com/hbat/2izf_B_BTN_300_ligplot_static.svg)

**Cooperativity chain detection and visualization (PDB Entry 6RSA):**

![Cooperativity chain detection and visualization](https://static.abhishek-tiwari.com/hbat/6rsa_chain_H_bond_chain_10.png)

## 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 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](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 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](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 | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](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:

[![arXiv](https://img.shields.io/badge/arXiv-2602.17712-b31b1b.svg)](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}, 
}
```

[![Chemrxiv](https://img.shields.io/badge/chemrxiv-15000141--v1-green)](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:

[![DOI HBAT](https://img.shields.io/badge/10.3233%2FISI-2007-00337?logo=doi&label=10.3233%2FISI-2007-00337&link=https%3A%2F%2Fdoi.org%2F10.3233%2FISI-2007-00337)](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

hbat

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README