Command-Line Interface

HBAT provides a comprehensive command-line interface (CLI) for batch processing and automation of molecular interaction analysis.

Basic Usage

hbat input.pdb [options]

The simplest usage requires only a PDB file as input:

hbat structure.pdb

This will analyze the structure using default parameters and display results to the console.

Command-Line Options

General Options

--version

Show the HBAT version and exit.

-h, --help

Show help message with all available options and exit.

Input/Output Options

input

Input PDB file (required for analysis).

-o OUTPUT, --output OUTPUT

Output text file for saving analysis results.

--json JSON_FILE

Export results to JSON format for programmatic access.

--csv CSV_FILE

Export results to CSV format for spreadsheet analysis.

Analysis Parameters

These options allow fine-tuning of the interaction detection criteria:

--hb-distance DISTANCE

Hydrogen bond H…A distance cutoff in Angstroms (default: 2.5 Å).

--hb-angle ANGLE

Hydrogen bond D-H…A angle cutoff in degrees (default: 120°).

--da-distance DISTANCE

Donor-acceptor distance cutoff in Angstroms (default: 3.5 Å).

--xb-distance DISTANCE

Halogen bond X…A distance cutoff in Angstroms (default: 3.5 Å).

--xb-angle ANGLE

Halogen bond C-X…A angle cutoff in degrees (default: 120°).

--pi-distance DISTANCE

π interaction H…π distance cutoff in Angstroms (default: 4.0 Å).

--pi-angle ANGLE

π interaction D-H…π angle cutoff in degrees (default: 120°).

--covalent-factor FACTOR

Covalent bond detection factor (default: 1.1). This factor is multiplied with the sum of covalent radii to determine if atoms are covalently bonded.

--mode {complete,local}

Analysis mode:

  • complete: Analyze all interactions (default)

  • local: Analyze only intra-residue interactions

Preset Management

HBAT includes predefined parameter sets for common analysis scenarios:

--preset PRESET_NAME

Load parameters from a preset file. Can be:

  • A preset name (e.g., high_resolution)

  • A path to a custom .hbat or .json preset file

Parameters from the preset can be overridden by subsequent command-line options.

--list-presets

List all available built-in presets with descriptions and exit.

Available built-in presets:

  • high_resolution: For structures with resolution < 1.5 Å

  • standard_resolution: For structures with resolution 1.5-2.5 Å

  • low_resolution: For structures with resolution > 2.5 Å

  • nmr_structures: Optimized for NMR-derived structures

  • drug_design_strict: Strict criteria for drug design applications

  • membrane_proteins: Adapted for membrane protein analysis

  • strong_interactions_only: Detect only strong interactions

  • weak_interactions_permissive: Include weaker interactions

Output Control

-v, --verbose

Enable verbose output with detailed progress information.

-q, --quiet

Quiet mode with minimal output (only errors).

--summary-only

Output only summary statistics without detailed interaction lists.

Analysis Filters

These options allow selective analysis of specific interaction types:

--no-hydrogen-bonds

Skip hydrogen bond analysis.

--no-halogen-bonds

Skip halogen bond analysis.

--no-pi-interactions

Skip π interaction analysis.

Examples

Basic analysis with default parameters:

hbat protein.pdb

Save results to a text file:

hbat protein.pdb -o results.txt

Use custom hydrogen bond criteria:

hbat protein.pdb --hb-distance 3.0 --hb-angle 150

Export results in multiple formats:

hbat protein.pdb -o results.txt --json results.json --csv results.csv

Use a high-resolution preset:

hbat protein.pdb --preset high_resolution

Use a preset with custom overrides:

hbat protein.pdb --preset drug_design_strict --hb-distance 3.0

Analyze only local interactions:

hbat protein.pdb --mode local

Quick summary with quiet output:

hbat protein.pdb -q --summary-only

Verbose analysis with specific interaction types:

hbat protein.pdb -v --no-pi-interactions

List available presets:

hbat --list-presets

Output Formats

Text Output

The default text output includes:

  • Analysis metadata (input file, timestamp)

  • Summary statistics

  • Detailed lists of each interaction type

  • Cooperativity chain information

JSON Output

The JSON format provides structured data with:

  • Metadata section with version and file information

  • Complete statistics

  • Arrays of interactions with all geometric parameters

  • Atom coordinates for further processing

CSV Output

The CSV format includes separate sections for:

  • Hydrogen bonds with all parameters

  • Halogen bonds with geometric data

  • π interactions with distance and angle information

Each section has appropriate column headers for easy import into spreadsheet applications.

Exit Codes

The CLI returns the following exit codes:

  • 0: Success

  • 1: General error (invalid input, analysis failure)

  • 130: Interrupted by user (Ctrl+C)

Integration with Scripts

The CLI is designed for easy integration with shell scripts and workflow systems:

#!/bin/bash
# Process multiple PDB files
for pdb in *.pdb; do
    echo "Processing $pdb..."
    hbat "$pdb" --json "${pdb%.pdb}_results.json" --quiet
done

# Python integration example
import subprocess
import json

result = subprocess.run(
    ['hbat', 'protein.pdb', '--json', 'output.json'],
    capture_output=True,
    text=True
)

if result.returncode == 0:
    with open('output.json') as f:
        data = json.load(f)
        print(f"Found {data['statistics']['hydrogen_bonds']} H-bonds")