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.

Main Classes
------------

PDBParser
~~~~~~~~~

.. autoclass:: hbat.core.pdb_parser.PDBParser
   :members:
   :undoc-members:
   :show-inheritance:

   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")

      # Advanced parsing with validation
      try:
          atoms, residues, bonds = parser.parse_file("complex.pdb")
          
          # Get comprehensive statistics
          stats = parser.get_statistics()
          print(f"Parsing time: {stats.parse_time:.2f} seconds")
          print(f"Has hydrogens: {parser.has_hydrogens()}")
          print(f"Chain count: {len(stats.chains)}")
          
      except Exception as e:
          print(f"Parsing failed: {e}")

   **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

Data Structure Classes
----------------------

Atom
~~~~

.. autoclass:: hbat.core.pdb_parser.Atom
   :members:
   :undoc-members:
   :show-inheritance:

   Comprehensive atomic data structure with PDB information and calculated properties.

   **Core Properties:**

   - **PDB Information**: Serial number, name, residue context, coordinates
   - **Chemical Properties**: Element, formal charge, occupancy, B-factor
   - **Geometric Properties**: 3D coordinates as Vec3D objects
   - **Connectivity**: Bond partners and chemical environment
   - **Validation**: Quality metrics and flags

   **Usage Example:**

   .. code-block:: python

      from hbat.core.pdb_parser import Atom
      from hbat.core.vector import Vec3D

      # Access atom properties
      atom = atoms[0]  # From parser results
      
      print(f"Atom: {atom.name} ({atom.element})")
      print(f"Residue: {atom.res_name} {atom.res_num}")
      print(f"Position: {atom.coord}")
      print(f"B-factor: {atom.b_factor:.2f}")

      # Geometric calculations
      distance = atom.coord.distance_to(other_atom.coord)
      print(f"Distance: {distance:.2f} Å")

Residue
~~~~~~~

.. autoclass:: hbat.core.pdb_parser.Residue
   :members:
   :undoc-members:
   :show-inheritance:

   Residue-level data structure containing atom collections and residue properties.

   **Properties:**

   - **Identification**: Residue name, number, chain, insertion code
   - **Atom Collections**: All atoms, backbone atoms, side chain atoms
   - **Chemical Classification**: Protein, DNA, RNA, or hetrogen residue
   - **Geometric Properties**: Center of mass, radius of gyration
   - **Connectivity**: Inter-residue bonds and interactions

   **Usage Example:**

   .. code-block:: python

      # Access residue information
      residue = residues[0]  # From parser results
      
      print(f"Residue: {residue.name} {residue.number}")
      print(f"Chain: {residue.chain}")
      print(f"Atom count: {len(residue.atoms)}")

      # Get specific atom types
      backbone_atoms = residue.get_backbone_atoms()
      sidechain_atoms = residue.get_sidechain_atoms()
      
      print(f"Backbone atoms: {len(backbone_atoms)}")
      print(f"Side chain atoms: {len(sidechain_atoms)}")

Bond
~~~~

.. autoclass:: hbat.core.pdb_parser.Bond
   :members:
   :undoc-members:
   :show-inheritance:

   Chemical bond representation with geometric and chemical properties.

   **Bond Properties:**

   - **Atom Partners**: Two atoms forming the covalent bond
   - **Bond Length**: Distance between bonded atoms
   - **Bond Type**: Single, double, triple, aromatic
   - **Chemical Environment**: Intra-residue vs. inter-residue bonds
   - **Validation**: Bond length validation against expected values

   **Usage Example:**

   .. code-block:: python

      # Analyze bond properties
      bond = bonds[0]  # From parser results
      
      print(f"Bond: {bond.atom1.name} - {bond.atom2.name}")
      print(f"Length: {bond.length:.3f} Å")
      print(f"Type: {bond.bond_type}")

      # Validate bond length
      if bond.is_valid_length():
          print("Bond length within expected range")

Parsing Methods
---------------

File Parsing
~~~~~~~~~~~~

.. automethod:: hbat.core.pdb_parser.PDBParser.parse_file

   Parse PDB file from disk with comprehensive error handling.

.. automethod:: hbat.core.pdb_parser.PDBParser.parse_lines

   Parse PDB content from string lines for in-memory processing.

Structure Analysis
~~~~~~~~~~~~~~~~~~

.. automethod:: hbat.core.pdb_parser.PDBParser.get_statistics

   Retrieve comprehensive parsing and structure statistics.

.. automethod:: hbat.core.pdb_parser.PDBParser.has_hydrogens

   Check if the parsed structure contains hydrogen atoms.

.. automethod:: hbat.core.pdb_parser.PDBParser.validate_structure

   Perform comprehensive structure validation and quality assessment.

Bond Detection
~~~~~~~~~~~~~~

.. automethod:: hbat.core.pdb_parser.PDBParser._detect_bonds

   Internal method for automatic covalent bond detection using distance criteria.

.. automethod:: hbat.core.pdb_parser.PDBParser._validate_bond

   Internal method for bond validation against chemical expectations.

Utility Functions
-----------------

Type Conversion
~~~~~~~~~~~~~~~

.. autofunction:: hbat.core.pdb_parser._safe_int_convert

   Safely convert values to integers with NaN and None handling.

.. autofunction:: hbat.core.pdb_parser._safe_float_convert

   Safely convert values to floats with robust error handling.

Error Handling
--------------

**Exception Types:**

The parser handles various error conditions gracefully:

- **File I/O Errors**: Missing files, permission issues, corrupted data
- **Format Errors**: Malformed PDB records, invalid coordinates
- **Chemical Errors**: Invalid atom types, impossible geometries
- **Memory Errors**: Structures too large for available memory

**Error Recovery:**

.. code-block:: python

   try:
       atoms, residues, bonds = parser.parse_file("problematic.pdb")
   except FileNotFoundError:
       print("PDB file not found")
   except ValueError as e:
       print(f"Invalid PDB format: {e}")
   except MemoryError:
       print("Structure too large for available memory")

**Validation Warnings:**

The parser provides detailed warnings for common issues:

- Missing atoms in standard residues
- Unusual bond lengths or angles
- Non-standard residue names
- Duplicate atom serial numbers
- Chain breaks and missing residues

Performance Optimization
------------------------

**Efficient Data Structures:**

- **Dataclasses**: Minimal memory overhead with fast attribute access
- **Vec3D Integration**: Optimized 3D coordinate handling
- **Lazy Evaluation**: Properties computed on-demand
- **Memory Pooling**: Efficient object reuse for large structures

**Algorithmic Optimizations:**

- **Spatial Indexing**: Fast neighbor searching for bond detection
- **Vectorized Operations**: NumPy-compatible coordinate processing
- **Chunked Processing**: Memory-efficient handling of large files
- **Parallel Parsing**: Future support for multi-threaded parsing

**Benchmarks:**

Typical performance on modern hardware:

- **Small proteins** (<1000 atoms): <10 ms parsing time
- **Medium proteins** (1000-10000 atoms): 10-100 ms parsing time  
- **Large complexes** (10000+ atoms): 100-1000 ms parsing time
- **Memory usage**: ~1-2 MB per 1000 atoms

Integration with Analysis Pipeline
----------------------------------

**Analyzer Integration:**

The parser integrates seamlessly with the analysis pipeline:

.. code-block:: python

   from hbat.core.analyzer import MolecularInteractionAnalyzerractionAnalyzer
   from hbat.core.pdb_parser import PDBParser

   # Direct integration
   analyzer = MolecularInteractionAnalyzerractionAnalyzer()
   results = analyzer.analyze_file("protein.pdb")  # Uses parser internally

   # Manual parsing for custom processing
   parser = PDBParser()
   atoms, residues, bonds = parser.parse_file("protein.pdb")
   
   # Custom pre-processing
   filtered_atoms = [a for a in atoms if a.element != 'H']
   
   # Analyze processed structure
   results = analyzer.analyze_structure(filtered_atoms, residues, bonds)

**Structure Fixing Integration:**

The parser works with the PDB fixer for structure enhancement:

.. code-block:: python

   from hbat.core.pdb_fixer import PDBFixer

   # Parse original structure
   parser = PDBParser()
   atoms, residues, bonds = parser.parse_file("original.pdb")

   # Apply structure fixing
   fixer = PDBFixer()
   fixed_structure = fixer.add_missing_hydrogens(atoms, residues)

   # Re-parse enhanced structure
   enhanced_atoms, enhanced_residues, enhanced_bonds = parser.parse_structure(fixed_structure)