Command-Line Interface

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 file for saving analysis results. The format is automatically detected from the file extension:

  • .txt - Text format (human-readable summary)

  • .csv - CSV format (single file with all interactions)

  • .json - JSON format (single file with structured data)

--json JSON_BASE#

Export results to multiple JSON files. Creates separate files for each interaction type:

  • {base}_h_bonds.json - Hydrogen bonds

  • {base}_x_bonds.json - Halogen bonds

  • {base}_pi_interactions.json - π interactions

  • {base}_cooperativity_chains.json - Cooperativity chains

--csv CSV_BASE#

Export results to multiple CSV files. Creates separate files for each interaction type:

  • {base}_h_bonds.csv - Hydrogen bonds

  • {base}_x_bonds.csv - Halogen bonds

  • {base}_pi_interactions.csv - π interactions

  • {base}_cooperativity_chains.csv - Cooperativity chains

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

PDB Fixing Options#

HBAT can automatically fix common PDB file issues before analysis:

--fix-pdb#

Enable automatic PDB fixing to resolve common structural issues like:

  • Missing hydrogen atoms

  • Incomplete residues

  • Chain breaks

  • Non-standard residues

--fix-method {pdbfixer,openbabel}#

Choose the method for PDB fixing (default: pdbfixer):

  • pdbfixer: Use PDBFixer (default method, recommended for protein structures)

  • openbabel: Use OpenBabel (alternative method)

--save-fixed PATH#

Save the fixed PDB structure to the specified file path. Useful for:

  • Inspecting the fixed structure

  • Reusing the fixed structure in other analyses

  • Quality control of the fixing process

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

Single File Output Formats#

Save results to different formats (auto-detected from extension):

hbat input.pdb                                    # Show results in terminal
hbat input.pdb -o results.csv                     # Save results to CSV file
hbat input.pdb -o results.json                    # Save results to JSON file

Multiple File Outputs#

Export to separate files for each interaction type:

hbat protein.pdb --csv results    # Creates multiple CSV files
hbat protein.pdb --json results   # Creates multiple JSON files

This creates files like: - results_h_bonds.csv - results_x_bonds.csv - results_pi_interactions.csv - results_cooperativity_chains.csv

PDB Fixing Examples#

Fix PDB structure automatically before analysis:

hbat input.pdb --fix-pdb                                    # Auto-fix using PDBFixer (default)
hbat input.pdb --fix-pdb --fix-method=pdbfixer              # Explicitly use PDBFixer
hbat input.pdb --fix-pdb --fix-method=openbabel             # Use OpenBabel for fixing

Save the fixed structure for inspection:

hbat input.pdb --fix-pdb --save-fixed input_fixed.pdb       # Save fixed structure
hbat input.pdb --fix-pdb --save-fixed input_fixed.pdb -o results.json  # Fix, save, and analyze

For structures missing hydrogen atoms:

hbat no_hydrogens.pdb --fix-pdb -o results.csv              # Fix and analyze
hbat crystal.pdb --fix-pdb --fix-method=pdbfixer --verbose  # Detailed fixing process

Custom Analysis Parameters#

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.csv --json results.json

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

Single File JSON Output#

When using -o results.json, HBAT creates a single JSON file containing all interactions with:

  • Metadata section with version and file information

  • Complete summary statistics

  • All interaction types in one structured file

Multiple File JSON Output#

When using --json results, HBAT creates separate JSON files for each interaction type:

  • results_h_bonds.json - Hydrogen bonds with donor-acceptor properties

  • results_x_bonds.json - Halogen bonds with geometric data

  • results_pi_interactions.json - π interactions with distance/angle data

  • results_cooperativity_chains.json - Cooperativity chain networks

Each file includes metadata and structured arrays with all geometric parameters and atom coordinates.

Single File CSV Output#

When using -o results.csv, HBAT creates a single CSV file with all interactions organized in sections:

  • Hydrogen bonds with D-A Properties and B/S classification

  • Halogen bonds with enhanced property columns

  • π interactions with structural information

  • Cooperativity chains with interaction networks

Multiple File CSV Output#

When using --csv results, HBAT creates separate CSV files for each interaction type:

  • results_h_bonds.csv - Hydrogen bonds with complete donor-acceptor properties

  • results_x_bonds.csv - Halogen bonds with geometric and structural data

  • results_pi_interactions.csv - π interactions with distance and angle information

  • results_cooperativity_chains.csv - Cooperativity chains showing interaction networks

When using --csv results.csv, HBAT creates: - results_h_bonds.csv - results_halogen_bonds.csv - results_pi_interactions.csv - results_cooperativity_chains.csv

Each file includes comprehensive data with 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 with automatic fixing
for pdb in *.pdb; do
    echo "Processing $pdb..."
    hbat "$pdb" --fix-pdb --json "${pdb%.pdb}_results.json" --quiet
done

# Process crystallographic structures (likely missing hydrogens)
for pdb in crystal_*.pdb; do
    echo "Processing crystal structure $pdb..."
    hbat "$pdb" --fix-pdb --fix-method=pdbfixer \
         --save-fixed "${pdb%.pdb}_fixed.pdb" \
         --csv "${pdb%.pdb}_analysis" --verbose
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")
Contents