Utilities

Utilities#

The utilities package contains utility functions that are used across different parts of HBAT. These functions provide common functionality for data processing, atom handling, GraphViz detection, and other operations that don’t fit into the core analysis modules.

Overview#

The utilities package is designed to:

  • Provide reusable utility functions for common operations

  • Centralize atom name processing and element mapping

  • Handle GraphViz detection and system integration

  • Support both performance-critical and general-purpose use cases

  • Maintain compatibility with existing code through the constants module

Modules#

Module Summary#

Atom Utilities

Atom name to element mapping utilities for PDB structures. Provides both comprehensive regex-based mapping and high-performance dictionary lookup functions.

GraphViz Utilities

GraphViz detection and system integration utilities. Handles automatic detection of GraphViz installations, version checking, and layout engine discovery across different platforms.

Key Features#

Atom Processing: - Comprehensive PDB atom name to element mapping - Support for complex PDB naming conventions - High-performance lookups for common atoms - Robust error handling and fallback mechanisms

GraphViz Integration: - Automatic detection of GraphViz installations - Cross-platform support (Windows, macOS, Linux) - Layout engine discovery and validation - Performance-optimized caching system

Design Principles: - Performance optimization for high-throughput processing - Backward compatibility with existing code - Clear separation of concerns - Comprehensive documentation and examples

Usage Examples#

Atom Utilities:

from hbat.utilities import pdb_atom_to_element, get_element_from_pdb_atom

# High-performance element mapping
element = pdb_atom_to_element('CA')  # Returns 'C'

# Comprehensive regex-based mapping
element = get_element_from_pdb_atom('CA2+')  # Returns 'CA'

# Both functions handle complex PDB naming
element = pdb_atom_to_element('C1\'')  # Returns 'C'
element = get_element_from_pdb_atom('H2\'\'')  # Returns 'H'

GraphViz Utilities:

from hbat.utilities.graphviz_utils import GraphVizDetector, get_graphviz_info

# Check GraphViz availability
if GraphVizDetector.is_graphviz_available():
    print("GraphViz is ready for advanced visualization")

# Get available layout engines
engines = GraphVizDetector.get_available_engines()
print(f"Available engines: {engines}")

# Get comprehensive system information
info = get_graphviz_info()
print(f"Version: {info['version']}, Engines: {info['engines']}")

Migration Notes#

The atom utility functions were moved from hbat.constants.pdb_constants to hbat.utilities.atom_utils for better code organization. For backward compatibility, these functions are still available through the constants module:

# New recommended import (direct from utilities)
from hbat.utilities import pdb_atom_to_element

# Still works (re-exported from constants)
from hbat.constants import pdb_atom_to_element

# Old import path (still works but not recommended)
from hbat.constants.pdb_constants import pdb_atom_to_element
Contents