Development Guide#
This guide helps developers set up and contribute to the HBAT project.
Quick Start#
Clone the repository
git clone https://github.com/abhishektiwari/hbat.git
cd hbat
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 .
Run tests
make test
# or
cd tests && python run_tests.py
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 analysisCLI Tests (
tests/cli/): Command-line argument validation, preset loading/saving, parameter overrides, output formattingGUI Tests (
tests/gui/): Parameter panels, results display, chain visualization, preset managementIntegration 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 setsExpected Results Validation: Benchmark validation using 6RSA.pdb structure
Coverage Reporting: HTML reports in
tests/htmlcov/with source highlightingCross-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 classAtom: Individual atom representationResidue: Amino acid residue representation
Analysis Engine (hbat.core.analysis)#
Core analysis functionality:
NPMolecularInteractionAnalyzer: Main analysis classAnalysisParameters: Configuration parametersDetection algorithms for hydrogen bonds, halogen bonds, π interactions
GUI Components (hbat.gui)#
Tkinter-based graphical interface:
MainWindow: Main application windowParameterPanel: Parameter configurationResultsPanel: 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:
Add detection method to
NPMolecularInteractionAnalyzerCreate corresponding data class (like
HydrogenBond)Update GUI results panel
Add CLI export support
Update documentation
New Analysis Parameters#
Add parameter to
AnalysisParametersdataclassUpdate GUI parameter panel
Add CLI argument
Update help documentation
New Export Formats#
Add export function to CLI module
Update argument parser
Add format validation
Update documentation
New Parameter Presets#
To add a new parameter preset:
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"
}
}
}
Add icon mapping in CLI
list_available_presets()functionTest preset loading in both GUI and CLI
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#
Vector Operations: Use efficient NumPy-like operations where possible
Memory Usage: Process large structures in chunks if needed
Algorithm Complexity: Prefer O(n log n) over O(n²) algorithms
Caching: Cache expensive calculations when appropriate
Contributing#
Pull Request Process#
Fork the repository
Create a feature branch
Make changes with tests
Run code quality checks
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.