hbat 2.2.8.dev26__tar.gz → 2.2.9.dev27__tar.gz

{hbat-2.2.8.dev26 → hbat-2.2.9.dev27}/.github/workflows/test.yml

@@ -21,6 +21,11 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
     
+    - name: Install GraphViz
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y graphviz
+    
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

{hbat-2.2.8.dev26 → hbat-2.2.9.dev27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hbat
-Version: 2.2.8.dev26
+Version: 2.2.9.dev27
 Summary: Hydrogen Bond Analysis Tool for PDB structures
 Author-email: Abhishek Tiwari <hbat@abhishek-tiwari.com>
 License-Expression: MIT
@@ -26,11 +26,14 @@ License-File: LICENSE
 Requires-Dist: pdbreader>=0.1.0
 Requires-Dist: numpy>=1.20.0
 Requires-Dist: networkx>=2.5.0
+Requires-Dist: graphviz>=0.20.0
+Requires-Dist: Pillow>=8.0.0
 Requires-Dist: matplotlib>=3.3.0
 Requires-Dist: openbabel-wheel>=3.1.1.22
 Requires-Dist: pybel>=0.15.5
 Requires-Dist: mmcif-pdbx>=2.0.1
 Requires-Dist: mmcif>=0.92.0
+Requires-Dist: tkinter-async-execute>=1.4.0
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=2.8.0; extra == "dev"
@@ -59,15 +62,8 @@ Requires-Dist: sphinx-sitemap>=2.7.2; extra == "docs"
 Requires-Dist: sphinx-autodoc-typehints>=1.10.0; extra == "docs"
 Provides-Extra: gui
 Requires-Dist: tkinter; python_version >= "3.8" and extra == "gui"
-Provides-Extra: advanced-viz
-Requires-Dist: seaborn>=0.11.0; extra == "advanced-viz"
-Requires-Dist: plotly>=5.0.0; extra == "advanced-viz"
-Provides-Extra: export
-Requires-Dist: pandas>=1.1.0; extra == "export"
-Requires-Dist: openpyxl>=3.0.0; extra == "export"
-Requires-Dist: xlwt>=1.3.0; extra == "export"
 Provides-Extra: all
-Requires-Dist: hbat[advanced-viz,docs,export,gui]; extra == "all"
+Requires-Dist: hbat[gui]; extra == "all"
 Dynamic: license-file
 
 ![HBAT](https://github.com/abhishektiwari/hbat/raw/main/hbat.svg)
@@ -102,6 +98,9 @@ HBAT v2  is a modern Python re-implementation of the original Perl-based tool de
 
 - **Comprehensive Analysis**: Detect and analyze potential hydrogen bonds, halogen bonds, and X-H...π interactions
 - **Dual Interface**: Both graphical (tkinter) and command-line interfaces
+- **Advanced Visualization**: Choice between NetworkX/matplotlib and GraphViz renderers for cooperativity chain visualization
+- **High-Quality Graphics**: Export visualizations to PNG, SVG, PDF with configurable resolution
+- **Interactive GUI**: Scrollable visualizations with dynamic layout switching and engine selection
 - **Parameter Presets**: Built-in presets for different structure types (high-resolution, NMR, membrane proteins, etc.)
 - **Flexible Parameters**: Customizable distance cutoffs, angle thresholds, and analysis modes.
 - **Multiple Output Formats**: Text, CSV, and JSON export options
@@ -172,6 +171,28 @@ conda install -c hbat hbat
 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

{hbat-2.2.8.dev26 → hbat-2.2.9.dev27}/README.md

@@ -30,6 +30,9 @@ HBAT v2  is a modern Python re-implementation of the original Perl-based tool de
 
 - **Comprehensive Analysis**: Detect and analyze potential hydrogen bonds, halogen bonds, and X-H...π interactions
 - **Dual Interface**: Both graphical (tkinter) and command-line interfaces
+- **Advanced Visualization**: Choice between NetworkX/matplotlib and GraphViz renderers for cooperativity chain visualization
+- **High-Quality Graphics**: Export visualizations to PNG, SVG, PDF with configurable resolution
+- **Interactive GUI**: Scrollable visualizations with dynamic layout switching and engine selection
 - **Parameter Presets**: Built-in presets for different structure types (high-resolution, NMR, membrane proteins, etc.)
 - **Flexible Parameters**: Customizable distance cutoffs, angle thresholds, and analysis modes.
 - **Multiple Output Formats**: Text, CSV, and JSON export options
@@ -100,6 +103,28 @@ conda install -c hbat hbat
 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

{hbat-2.2.8.dev26 → hbat-2.2.9.dev27}/docs/source/api/ccd/constants_generator.rst

@@ -8,7 +8,7 @@ This module provides functionality to generate Python constants files from CCD d
 Classes
 -------
 
-.. autoclass:: ConstantsGenerator
+.. autoclass:: CCDConstantsGenerator
    :members:
    :undoc-members:
    :show-inheritance:
@@ -19,9 +19,7 @@ Classes
    .. autosummary::
       :nosignatures:
       
-      extract_residue_bonds
-      generate_constants_file
-      write_constants_file
+      write_residue_bonds_constants
 
    .. rubric:: Attributes
 
@@ -30,13 +28,6 @@ Classes
 
       Instance of CCDDataManager for accessing CCD data
 
-Functions
----------
-
-.. autofunction:: main
-
-   Command-line interface for generating residue bond constants.
-
    Usage:
       .. code-block:: bash
 
@@ -102,22 +93,16 @@ Usage Example
 
 .. code-block:: python
 
-   from hbat.ccd.constants_generator import ConstantsGenerator
+   from hbat.ccd.constants_generator import CCDConstantsGenerator
    from hbat.ccd.ccd_analyzer import CCDDataManager
 
    # Initialize generator
    ccd_manager = CCDDataManager()
-   generator = ConstantsGenerator(ccd_manager)
+   generator = CCDConstantsGenerator(ccd_manager)
 
-   # Extract bonds for specific residues
+   # Generate constants file for specific residues
    residue_list = ["ALA", "GLY", "VAL"]
-   bonds_data = generator.extract_residue_bonds(residue_list)
-
-   # Generate full constants file
-   generator.generate_constants_file("my_constants.py")
-
-   # Or write specific data
-   generator.write_constants_file(bonds_data, "partial_constants.py")
+   success = generator.write_residue_bonds_constants(residue_list, "my_constants.py")
 
 Performance Benefits
 --------------------

{hbat-2.2.8.dev26 → hbat-2.2.9.dev27}/docs/source/api/cli/index.rst

@@ -4,9 +4,4 @@ Main CLI Module
 .. automodule:: hbat.cli.main
    :members:
    :undoc-members:
-   :show-inheritance:
-
-Functions
-~~~~~~~~~
-
-.. autofunction:: hbat.cli.main.main
+   :show-inheritance:

{hbat-2.2.8.dev26 → hbat-2.2.9.dev27}/docs/source/api/constants/atomic_data.rst

@@ -7,17 +7,6 @@ Module Overview
 ---------------
 
 .. automodule:: hbat.constants.atomic_data
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Classes
--------
-
-Atomic Data
-~~~~~~~~~~~
-
-.. autoclass:: hbat.constants.atomic_data.AtomicData
    :members:
    :undoc-members:
    :show-inheritance:

hbat-2.2.9.dev27/docs/source/api/constants/misc.rst

@@ -0,0 +1,12 @@
+Miscellaneous Constants
+=======================
+
+Contains GUI defaults, file formats, and other miscellaneous constants.
+
+Module Overview
+---------------
+
+.. automodule:: hbat.constants.misc
+   :members:
+   :undoc-members:
+   :show-inheritance:

hbat-2.2.9.dev27/docs/source/api/constants/parameters.rst

@@ -0,0 +1,12 @@
+Analysis Parameters
+===================
+
+Contains analysis parameters, default values, and validation ranges for molecular interaction analysis.
+
+Module Overview
+---------------
+
+.. automodule:: hbat.constants.parameters
+   :members:
+   :undoc-members:
+   :show-inheritance:

{hbat-2.2.8.dev26 → hbat-2.2.9.dev27}/docs/source/api/core/pdb_fixer.rst

@@ -183,150 +183,41 @@ Exception Classes
 Core Fixing Methods
 -------------------
 
-Hydrogen Addition
-~~~~~~~~~~~~~~~~~
-
-.. automethod:: hbat.core.pdb_fixer.PDBFixer.add_missing_hydrogens
-
-   Add missing hydrogen atoms using chemical bonding rules and geometric optimization.
-
-   **Algorithm Details:**
-
-   1. **Identify Missing Hydrogens**: Compare with expected atom counts
-   2. **Determine Bonding Geometry**: Analyze local chemical environment
-   3. **Calculate Positions**: Use ideal bond lengths and angles
-   4. **Geometric Optimization**: Minimize steric clashes
-   5. **Validation**: Check for reasonable H-bond geometries
-
-   **Chemical Rules:**
-
-   - **sp³ Carbons**: Tetrahedral geometry (109.5°)
-   - **sp² Carbons**: Trigonal planar geometry (120°)
-   - **Nitrogens**: Pyramidal or planar based on hybridization
-   - **Oxygens**: Bent geometry for alcohols, linear for carbonyls
-
-Heavy Atom Reconstruction
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. automethod:: hbat.core.pdb_fixer.PDBFixer.add_missing_heavy_atoms
-
-   Reconstruct missing heavy atoms in standard protein and nucleic acid residues.
+The PDBFixer class provides comprehensive structure fixing capabilities through its member methods. All methods are documented through the class autodocumentation above.
 
-   **Reconstruction Strategy:**
-
-   1. **Template Matching**: Use ideal residue geometries
-   2. **Coordinate Transformation**: Align existing atoms with templates
-   3. **Position Calculation**: Place missing atoms using transformations
-   4. **Clash Resolution**: Adjust positions to avoid overlaps
-   5. **Energy Minimization**: Optimize local geometry
-
-Residue Standardization
-~~~~~~~~~~~~~~~~~~~~~~~
-
-.. automethod:: hbat.core.pdb_fixer.PDBFixer.convert_nonstandard_residues
-
-   Convert non-standard and modified residues to their standard equivalents.
-
-   **Conversion Rules:**
-
-   - **Modified Amino Acids**: Map to parent amino acid (e.g., MSE → MET)
-   - **Protonation States**: Standardize histidine variants (HIS, HID, HIE)
-   - **Post-translational Modifications**: Convert to unmodified forms
-   - **Non-standard Nucleotides**: Map to canonical bases
-
-   **Database Integration:**
-
-   Uses comprehensive substitution tables from the constants module:
-
-   .. code-block:: python
+**Key Method Categories:**
 
-      from hbat.constants import PROTEIN_SUBSTITUTIONS
+- **Hydrogen Addition**: `add_missing_hydrogens()` - Uses chemical bonding rules and geometric optimization
+- **Heavy Atom Reconstruction**: `add_missing_heavy_atoms()` - Reconstructs missing heavy atoms in standard residues  
+- **Residue Standardization**: `convert_nonstandard_residues()` - Converts non-standard and modified residues
+- **Hetrogen Management**: `remove_heterogens()` - Manages hetrogen retention based on analysis requirements
+- **File Operations**: `fix_structure_file()` - High-level interface for comprehensive PDB fixing
 
-      # Example conversions
-      conversions = {
-          "MSE": "MET",  # Selenomethionine → Methionine
-          "CSO": "CYS",  # Cysteine sulfenic acid → Cysteine  
-          "HYP": "PRO",  # Hydroxyproline → Proline
-          "PCA": "GLU"   # Pyroglutamic acid → Glutamic acid
-      }
-
-Hetrogen Management
-~~~~~~~~~~~~~~~~~~~
-
-.. automethod:: hbat.core.pdb_fixer.PDBFixer.remove_heterogens
-
-   Remove or retain specific heterogens based on analysis requirements.
-
-   **Hetrogen Categories:**
-
-   - **Waters**: HOH, WAT, DOD molecules
-   - **Ions**: Metal ions and simple salts
-   - **Cofactors**: Essential prosthetic groups
-   - **Ligands**: Small molecule binding partners
-   - **Crystallographic Additives**: PEG, glycerol, buffer components
-
-   **Retention Strategies:**
-
-   - **Keep All**: Retain all heterogens for comprehensive analysis
-   - **Keep Essential**: Retain only biologically relevant heterogens
-   - **Remove All**: Remove all heterogens for protein-only analysis
-   - **Custom Filtering**: User-defined retention criteria
-
-File-Level Operations
----------------------
+Standalone Functions
+--------------------
 
-Structure File Fixing
+Module-Level Functions
 ~~~~~~~~~~~~~~~~~~~~~~
 
-.. automethod:: hbat.core.pdb_fixer.PDBFixer.fix_structure_file
-
-   High-level interface for fixing PDB files with comprehensive options.
-
-   **Process Flow:**
-
-   1. **Parse Input**: Load and validate input PDB structure
-   2. **Apply Fixes**: Execute requested fixing operations in optimal order
-   3. **Validate Results**: Check fixed structure for consistency
-   4. **Write Output**: Save enhanced structure to output file
-   5. **Generate Report**: Provide detailed fixing statistics
-
-   **Output Formats:**
-
-   - **Standard PDB**: Traditional PDB format with fixed structure
-   - **Enhanced PDB**: PDB with additional metadata and validation info
-   - **Statistics Report**: Detailed log of all fixing operations
-
-Convenience Functions
----------------------
-
-Quick Fixing Operations
-~~~~~~~~~~~~~~~~~~~~~~~
-
-.. autofunction:: hbat.core.pdb_fixer.add_hydrogens_to_file
-
-   Convenience function for quick hydrogen addition to PDB files.
+.. autofunction:: hbat.core.pdb_fixer.add_missing_hydrogens
 
-.. autofunction:: hbat.core.pdb_fixer.standardize_residues_in_file
+   Standalone function for adding missing hydrogen atoms to atom lists.
 
-   Convenience function for residue standardization without other modifications.
+.. autofunction:: hbat.core.pdb_fixer.fix_pdb_file
 
-.. autofunction:: hbat.core.pdb_fixer.clean_structure_file
+   Convenience function for fixing PDB files with comprehensive options.
 
-   Convenience function for comprehensive structure cleaning and validation.
+.. autofunction:: hbat.core.pdb_fixer.add_missing_heavy_atoms
 
-Structure Validation
-~~~~~~~~~~~~~~~~~~~~~
+   Standalone function for reconstructing missing heavy atoms.
 
-.. autofunction:: hbat.core.pdb_fixer.validate_pdb_structure
+.. autofunction:: hbat.core.pdb_fixer.convert_nonstandard_residues
 
-   Comprehensive structure validation with detailed quality reporting.
+   Standalone function for converting non-standard residues.
 
-   **Validation Checks:**
+.. autofunction:: hbat.core.pdb_fixer.remove_heterogens
 
-   - **Atomic Completeness**: Missing atoms in standard residues
-   - **Geometric Consistency**: Bond lengths, angles, and chirality
-   - **Chemical Validity**: Proper atom types and formal charges
-   - **Structural Integrity**: Chain continuity and proper termination
+   Standalone function for removing heterogens from atom lists.
 
 Chemical Intelligence
 ---------------------

hbat-2.2.9.dev27/docs/source/api/core/pdb_parser.rst

@@ -0,0 +1,204 @@
+PDB File Parser
+===============
+
+High-performance PDB file parsing and molecular structure handling using the pdbreader library.
+
+Module Overview
+---------------
+
+.. automodule:: hbat.core.pdb_parser
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   This module provides comprehensive PDB file parsing capabilities with robust error handling, automatic bond detection, and structure validation. It uses the pdbreader library for efficient parsing and provides structured data access through dataclass objects.
+
+   High-performance PDB file parser with integrated structure analysis capabilities.
+
+   **Key Features:**
+
+   - **Robust Parsing**: Handles malformed PDB files with comprehensive error recovery
+   - **Automatic Bond Detection**: Identifies covalent bonds using distance criteria and atomic data
+   - **Element Mapping**: Uses utility functions for accurate atom type identification
+   - **Structure Validation**: Provides comprehensive structure quality assessment
+   - **Performance Optimization**: Efficient processing of large molecular complexes
+
+   **Usage Examples:**
+
+   .. code-block:: python
+
+      from hbat.core.pdb_parser import PDBParser
+
+      # Basic parsing
+      parser = PDBParser()
+      atoms, residues, bonds = parser.parse_file("protein.pdb")
+
+      print(f"Parsed {len(atoms)} atoms")
+      print(f"Found {len(residues)} residues")
+      print(f"Detected {len(bonds)} bonds")
+
+      # Structure analysis
+      stats = parser.get_statistics()
+      has_h = parser.has_hydrogens()
+      
+      print(f"Structure statistics: {stats}")
+      print(f"Contains hydrogens: {has_h}")
+
+   **Performance Characteristics:**
+
+   - Processes ~50,000 atoms per second on modern hardware
+   - Memory usage scales linearly with structure size
+   - Efficient handling of large protein complexes (>100k atoms)
+   - Optimized for both single structures and batch processing
+
+Key Features
+------------
+
+**Data Structure Classes:**
+
+- **PDBParser**: High-performance PDB file parser with integrated structure analysis 
+- **Atom**: Comprehensive atomic data structure with PDB information and calculated properties
+- **Residue**: Residue-level data structure containing atom collections and properties  
+- **Bond**: Chemical bond representation with geometric and chemical properties
+
+**Core Capabilities:**
+
+- **File Parsing**: Robust parsing with comprehensive error handling
+- **Structure Analysis**: Comprehensive statistics and quality assessment
+- **Bond Detection**: Automatic covalent bond identification using distance criteria
+- **Data Access**: Structured access to atoms, residues, and connectivity information
+
+All classes and methods are fully documented through the module autodocumentation above.
+
+Chemical Intelligence
+---------------------
+
+**Bond Detection Algorithm:**
+
+The parser uses sophisticated chemical rules for automatic bond detection:
+
+1. **Distance-Based Detection**: Uses covalent radii and distance cutoffs
+2. **Element-Specific Rules**: Different criteria for different element pairs
+3. **Chemical Validation**: Validates bonds against expected chemical properties
+4. **Performance Optimization**: Efficient spatial indexing for large structures
+
+**Atom Type Recognition:**
+
+- Automatic element detection from atom names
+- Handling of non-standard atom naming conventions
+- Support for modified residues and heterogens
+- Integration with atomic property databases
+
+Performance and Scalability
+---------------------------
+
+**Computational Complexity:**
+
+- **File Parsing**: O(n) where n is number of atoms
+- **Bond Detection**: O(n log n) using spatial indexing
+- **Structure Analysis**: O(n) linear operations
+- **Memory Usage**: Minimal overhead beyond raw structure data
+
+**Benchmarks:**
+
+Typical performance on modern hardware:
+
+- **Small proteins** (<1000 atoms): <50 ms parsing time
+- **Medium proteins** (1000-10000 atoms): 50-500 ms parsing time  
+- **Large complexes** (10000+ atoms): 500ms-5s parsing time
+
+Integration Examples
+--------------------
+
+Analysis Pipeline Integration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from hbat.core.pdb_parser import PDBParser
+   from hbat.core.analyzer import MolecularInteractionAnalyzer
+
+   # Complete analysis pipeline
+   def analyze_structure(pdb_file):
+       # Parse structure
+       parser = PDBParser()
+       atoms, residues, bonds = parser.parse_file(pdb_file)
+       
+       print(f"Parsed structure with {len(atoms)} atoms")
+       
+       # Get parsing statistics
+       stats = parser.get_statistics()
+       print(f"Statistics: {stats}")
+       
+       # Check hydrogen content
+       has_hydrogens = parser.has_hydrogens()
+       if not has_hydrogens:
+           print("Warning: Structure lacks hydrogen atoms")
+       
+       return atoms, residues, bonds
+
+Batch Processing
+~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import os
+   from concurrent.futures import ProcessPoolExecutor
+
+   def parse_structure_batch(pdb_files):
+       """Parse multiple PDB structures in parallel."""
+       
+       def parse_single_file(pdb_file):
+           parser = PDBParser()
+           try:
+               atoms, residues, bonds = parser.parse_file(pdb_file)
+               return {
+                   "file": pdb_file, 
+                   "success": True, 
+                   "atom_count": len(atoms),
+                   "residue_count": len(residues),
+                   "bond_count": len(bonds)
+               }
+           except Exception as e:
+               return {"file": pdb_file, "success": False, "error": str(e)}
+       
+       # Process files in parallel
+       with ProcessPoolExecutor() as executor:
+           results = list(executor.map(parse_single_file, pdb_files))
+       
+       # Summarize results
+       successful = [r for r in results if r["success"]]
+       failed = [r for r in results if not r["success"]]
+       
+       print(f"Successfully parsed {len(successful)} structures")
+       print(f"Failed to parse {len(failed)} structures")
+       
+       return results
+
+Quality Control
+---------------
+
+**Validation Metrics:**
+
+The parser provides comprehensive quality metrics:
+
+.. code-block:: python
+
+   # Quality assessment after parsing
+   parser = PDBParser()
+   atoms, residues, bonds = parser.parse_file("structure.pdb")
+   
+   stats = parser.get_statistics()
+   print(f"Structure Quality Metrics:")
+   print(f"  Total atoms: {stats['total_atoms']}")
+   print(f"  Protein atoms: {stats['protein_atoms']}")
+   print(f"  Water molecules: {stats['water_count']}")
+   print(f"  Heterogens: {stats['hetrogen_count']}")
+
+**Common Issues and Solutions:**
+
+- **Missing Atoms**: Detected and reported in statistics
+- **Invalid Coordinates**: Flagged during parsing
+- **Unusual Residues**: Identified and classified appropriately  
+- **Bond Detection Issues**: Comprehensive error reporting and recovery
+- **File Format Problems**: Robust error handling with detailed messages