Development Guide#

This guide helps developers set up and contribute to the HBAT project.

Quick Start#

  1. Clone the repository

git clone https://github.com/abhishektiwari/hbat.git
cd hbat
  1. Set up development environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements-dev.txt
pip install -e .
  1. Run tests

make test
# or
cd tests && python run_tests.py
  1. Try the applications

# CLI
python hbat_cli.py example_pdb_files/6rsa.pdb --verbose

# GUI (if tkinter available)
python hbat_gui.py

Project Structure#

hbat/
├── hbat/                   # Main package
│   ├── constants/         # Constants and defaults
│   │   ├── __init__.py    # Constants package interface
│   │   ├── constants.py   # Analysis defaults and atomic data
│   │   └── pdb_constants.py # PDB structure constants, residue mappings, and aromatic ring definitions
│   ├── core/              # Core analysis logic
│   │   ├── np_vector.py   # NumPy-based 3D vector mathematics
│   │   ├── pdb_parser.py  # PDB file parsing
│   │   ├── pdb_fixer.py   # PDB structure fixing and enhancement
│   │   └── analysis.py    # Main analysis engine
│   ├── gui/               # GUI components
│   │   ├── main_window.py # Main application window
│   │   ├── parameter_panel.py # Parameter configuration
│   │   ├── results_panel.py   # Results display
│   │   └── chain_visualization.py # Chain visualization window
│   └── cli/               # Command-line interface
│       └── main.py        # CLI implementation
├── example_presets/       # Built-in parameter presets
│   ├── high_resolution.hbat
│   ├── standard_resolution.hbat
│   ├── drug_design_strict.hbat
│   └── *.hbat             # Other preset files
├── tests/                # Test suite
│   ├── README.md         # Test documentation
│   ├── conftest.py       # Pytest configuration and fixtures
│   ├── run_tests.py      # Main test runner script
│   ├── core/             # Core module tests
│   │   ├── test_np_vector.py    # NumPy vector mathematics tests
│   │   ├── test_pdb_parser.py   # PDB parsing tests
│   │   └── test_analysis.py     # Analysis engine tests
│   ├── cli/              # CLI module tests
│   │   └── test_cli_main.py     # CLI and preset tests
│   └── gui/              # GUI module tests
│       └── test_gui_components.py # GUI component tests
├── hbat_gui.py           # GUI entry point
├── hbat_cli.py           # CLI entry point
├── pytest.ini           # Pytest configuration
├── requirements*.txt     # Dependencies
├── PARAMETERS.md         # Parameter documentation
└── pyproject.toml        # Package configuration

Development Workflow#

Code Style#

We use Python standard tools for code quality:

# Format code
make format

# Check style
make lint

# Type checking
make type-check

Testing#

The project uses a comprehensive, modular test suite with both pytest and custom test runner support. The test architecture is organized by module with flexible execution options and extensive coverage reporting.

# Run all tests (recommended)
make test

# Run fast tests only (skip slow integration tests)
make test-fast

# Test specific components
make test-core      # Core module tests (vector, parser, analysis)
make test-cli       # CLI tests (argument parsing, presets)
make test-gui       # GUI tests (components, imports)
make test-coverage  # Generate HTML coverage report

# Advanced test options with custom runner
cd tests && python run_tests.py --help        # See all options
cd tests && python run_tests.py --fast        # Skip slow tests
cd tests && python run_tests.py --core        # Core tests only
cd tests && python run_tests.py --integration # Integration tests only
cd tests && python run_tests.py --coverage    # Generate coverage report
cd tests && python run_tests.py --no-gui      # Skip GUI tests

# Direct pytest usage (modern approach)
pytest tests/ -v                              # All tests with verbose output
pytest tests/core/ -v                         # Core module tests only
pytest tests/cli/ -v                          # CLI module tests only
pytest tests/gui/ -v                          # GUI module tests only
pytest tests/ -m "not slow" -v               # Skip slow integration tests
pytest tests/ -m "unit" -v                   # Run unit tests only
pytest tests/ --cov=hbat --cov-report=html   # With HTML coverage report
pytest tests/ --cov=hbat --cov-report=term   # With terminal coverage report

# Manual end-to-end testing
python hbat_cli.py example_pdb_files/6rsa.pdb --json results.json --verbose
python hbat_cli.py example_pdb_files/2izf.pdb --preset high_resolution --csv output.csv

Test Structure#

The test suite follows a modular architecture with clear separation of concerns:

tests/
├── conftest.py                 # Shared fixtures and test configuration
├── run_tests.py               # Custom test runner with advanced options
├── README.md                  # Comprehensive test documentation
├── core/                      # Core functionality tests
│   ├── test_np_vector.py      # NumPy 3D vector mathematics, geometric calculations
│   ├── test_pdb_parser.py     # PDB file parsing, atom/residue handling
│   ├── test_pdb_fixer.py      # PDB structure fixing and enhancement
│   └── test_analysis.py       # Analysis algorithms, interaction detection
├── cli/                       # Command-line interface tests
│   └── test_cli_main.py       # Argument parsing, preset management, integration
├── gui/                       # Graphical user interface tests
│   └── test_gui_components.py # GUI component testing, widget behavior
└── htmlcov/                   # HTML coverage reports (generated)

docs/
├── source/                    # Sphinx documentation source
│   ├── api/                   # API documentation
│   │   ├── core/              # Core module documentation
│   │   ├── cli/               # CLI module documentation
│   │   ├── gui/               # GUI module documentation
│   │   ├── constants.rst      # Constants and configuration
│   │   └── index.rst          # API reference index
│   ├── _static/               # Static assets (logos, CSS)
│   ├── _templates/            # Custom Sphinx templates
│   ├── conf.py                # Sphinx configuration
│   ├── index.rst              # Documentation home page
│   ├── installation.rst       # Installation guide
│   ├── quickstart.rst         # Quick start tutorial
│   ├── cli.rst                # Command-line interface guide
│   ├── parameters.rst         # Analysis parameters documentation
│   ├── pdbfixing.rst          # PDB structure fixing guide
│   ├── logic.rst              # Algorithm and calculation logic
│   ├── examples.rst           # Usage examples
│   └── development.rst        # Development guide
├── build/                     # Generated documentation (HTML, PDF)
├── requirements.txt           # Documentation build dependencies
├── Makefile                   # Documentation build commands (Unix)
├── make.bat                   # Documentation build commands (Windows)
└── .readthedocs.yaml          # Read the Docs configuration

Module Test Coverage:

  • Core Tests (tests/core/): Vector operations, PDB parsing, PDB structure fixing, hydrogen bond detection, π-interactions, cooperativity analysis

  • CLI Tests (tests/cli/): Command-line argument validation, preset loading/saving, parameter overrides, output formatting

  • GUI Tests (tests/gui/): Parameter panels, results display, chain visualization, preset management

  • Integration Tests: End-to-end workflows using real PDB structures (6RSA.pdb, 2IZF.pdb)

Test Framework Features#

Pytest Markers for Test Categorization:

  • ``unit``: Fast, isolated unit tests (default for most tests)

  • ``integration``: Tests requiring sample PDB files and full workflows

  • ``slow``: Integration tests that take longer to run (>1 second)

  • ``gui``: Tests requiring GUI components (automatically skipped without display)

  • ``atomic``: Atomic property lookup and validation tests

  • ``cooperativity``: Cooperativity chain analysis tests

  • ``preset``: Parameter preset functionality tests

Shared Test Infrastructure:

  • Fixtures (conftest.py): Sample PDB files, preconfigured analyzers, standard parameter sets

  • Expected Results Validation: Benchmark validation using 6RSA.pdb structure

  • Coverage Reporting: HTML reports in tests/htmlcov/ with source highlighting

  • Cross-Platform Compatibility: Automatic GUI test skipping when no display available

  • Multiple Test Runners: Both modern pytest and legacy custom runner support

Test Data and Validation#

Sample Structures:

  • 6RSA.pdb: Primary test structure (>2000 atoms, >100 residues)

  • 2IZF.pdb: Secondary test structure for additional validation

Requirements Files#

  • requirements.txt: Core production dependencies (pdbreader, networkx, matplotlib)

  • requirements-dev.txt: Development dependencies (pytest, coverage, linting tools, type checking)

  • pyproject.toml: Package configuration with optional dependencies for visualization and export

Building and Distribution#

# Build package
make build

# Check package
make check

# Install in development mode
pip install -e .

# Install with optional dependencies
pip install -e .[dev,visualization,export]

Core Components#

PDB Parser (hbat.core.pdb_parser)#

Handles PDB file parsing:

  • PDBParser: Main parser class

  • Atom: Individual atom representation

  • Residue: Amino acid residue representation

Analysis Engine (hbat.core.analysis)#

Core analysis functionality:

  • NPMolecularInteractionAnalyzer: Main analysis class

  • AnalysisParameters: Configuration parameters

  • Detection algorithms for hydrogen bonds, halogen bonds, π interactions

GUI Components (hbat.gui)#

Tkinter-based graphical interface:

  • MainWindow: Main application window

  • ParameterPanel: Parameter configuration

  • ResultsPanel: Results display and export

CLI Interface (hbat.cli)#

Command-line interface with full functionality:

  • Argument parsing and validation

  • Multiple output formats (text, JSON, CSV)

  • Parameter preset support

  • Batch processing capabilities

Parameter Presets (example_presets/)#

Built-in parameter presets for common analysis scenarios:

  • JSON format with structured parameter organization

  • Optimized for different structure types and analysis goals

  • Support for custom user presets

  • CLI and GUI integration for easy loading

Adding New Features#

New Interaction Types#

To add a new molecular interaction type:

  1. Add detection method to NPMolecularInteractionAnalyzer

  2. Create corresponding data class (like HydrogenBond)

  3. Update GUI results panel

  4. Add CLI export support

  5. Update documentation

New Analysis Parameters#

  1. Add parameter to AnalysisParameters dataclass

  2. Update GUI parameter panel

  3. Add CLI argument

  4. Update help documentation

New Export Formats#

  1. Add export function to CLI module

  2. Update argument parser

  3. Add format validation

  4. Update documentation

New Parameter Presets#

To add a new parameter preset:

  1. Create JSON file in example_presets/ directory:

{
  "format_version": "1.0",
  "application": "HBAT",
  "created": "2024-01-15T10:30:00.000000",
  "description": "Brief description of preset purpose",
  "parameters": {
    "hydrogen_bonds": {
      "h_a_distance_cutoff": 3.5,
      "dha_angle_cutoff": 120.0,
      "d_a_distance_cutoff": 4.0
    },
    "halogen_bonds": {
      "x_a_distance_cutoff": 4.0,
      "cxa_angle_cutoff": 120.0
    },
    "pi_interactions": {
      "h_pi_distance_cutoff": 4.5,
      "dh_pi_angle_cutoff": 90.0
    },
    "general": {
      "covalent_cutoff_factor": 0.85,
      "analysis_mode": "complete"
    }
  }
}
  1. Add icon mapping in CLI list_available_presets() function

  2. Test preset loading in both GUI and CLI

  3. Update documentation in PARAMETERS.md

Testing Guidelines#

Unit Tests#

Create tests in the appropriate module directory under tests/:

# tests/core/test_new_feature.py
import pytest
from hbat.core.new_module import NewClass

class TestNewFeature:
    """Test cases for new functionality."""

    def test_new_feature(self):
        """Test description."""
        # Test implementation
        instance = NewClass()
        result = instance.method()
        assert result == expected_result

    @pytest.mark.slow
    def test_slow_feature(self):
        """Test that takes longer to run."""
        # Marked as slow - will be skipped with --fast
        pass

Integration Tests#

Test complete workflows using shared fixtures:

# tests/core/test_analysis.py
import pytest
from tests.conftest import ExpectedResults, validate_hydrogen_bond

@pytest.mark.integration
class TestAnalysisWorkflow:
    """Integration tests for analysis workflows."""

    def test_complete_analysis(self, sample_pdb_file, analyzer):
        """Test complete analysis workflow."""
        success = analyzer.analyze_file(sample_pdb_file)
        assert success
        assert len(analyzer.hydrogen_bonds) >= ExpectedResults.MIN_HYDROGEN_BONDS

        # Validate results quality
        for hbond in analyzer.hydrogen_bonds:
            validate_hydrogen_bond(hbond)

Test Markers#

Use pytest markers to categorize tests:

@pytest.mark.slow           # Skip with --fast
@pytest.mark.gui            # Requires GUI components
@pytest.mark.integration    # Requires sample files
@pytest.mark.unit          # Fast, isolated tests
@pytest.mark.atomic        # Atomic property tests
@pytest.mark.cooperativity # Cooperativity analysis tests
@pytest.mark.preset        # Preset functionality tests

Manual Testing#

Always test both GUI and CLI interfaces:

# CLI testing with sample files
python hbat_cli.py example_pdb_files/6rsa.pdb --verbose
python hbat_cli.py example_pdb_files/2izf.pdb --json results.json

# GUI testing
python hbat_gui.py  # Load example_pdb_files/6rsa.pdb through interface

Test Configuration#

The test suite uses modern configuration with multiple files for different aspects:

  • pytest.ini: Core pytest configuration, marker definitions, and test discovery

  • pyproject.toml: Advanced pytest configuration with coverage settings and dependency management

  • tests/conftest.py: Shared fixtures, test utilities, and expected results validation

  • tests/README.md: Comprehensive test documentation and usage examples

  • tests/run_tests.py: Custom test runner with advanced filtering and reporting options

Expected Results#

Tests use the ExpectedResults class in conftest.py for benchmark validation:

# With 6RSA.pdb structure (comprehensive validation)
ExpectedResults.MIN_HYDROGEN_BONDS = 100      # Minimum hydrogen bonds detected
ExpectedResults.MIN_PI_INTERACTIONS = 5       # Minimum π-interactions detected
ExpectedResults.MIN_COOPERATIVITY_CHAINS = 5  # Minimum cooperativity chains
ExpectedResults.MIN_TOTAL_INTERACTIONS = 50   # Minimum total validated interactions
ExpectedResults.MIN_ATOMS = 2000              # Minimum atoms in test structure
ExpectedResults.MIN_RESIDUES = 100            # Minimum residues in test structure

These benchmarks ensure consistent analysis quality across different development environments and detect regressions in analysis algorithms.

Preset Testing#

Test preset functionality thoroughly:

# Test preset listing
python -m hbat.cli.main --list-presets

# Test preset loading
python -m hbat.cli.main test_file.pdb --preset high_resolution --verbose

# Test preset with overrides
python -m hbat.cli.main test_file.pdb --preset standard_resolution --hb-distance 3.0

# Test GUI preset loading and saving
python hbat_gui.py  # Use Load/Save Preset buttons

Performance Considerations#

Optimization Guidelines#

  1. Vector Operations: Use efficient NumPy-like operations where possible

  2. Memory Usage: Process large structures in chunks if needed

  3. Algorithm Complexity: Prefer O(n log n) over O(n²) algorithms

  4. Caching: Cache expensive calculations when appropriate

Contributing#

Pull Request Process#

  1. Fork the repository

  2. Create a feature branch

  3. Make changes with tests

  4. Run code quality checks

  5. Submit pull request with description

Code Review Checklist#

  • [ ] Code follows style guidelines

  • [ ] Tests pass

  • [ ] Documentation updated

  • [ ] No performance regressions

  • [ ] Backwards compatibility maintained

License#

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