Graphical User Interface

The GUI module provides graphical interface components for HBAT, including comprehensive parameter management, preset handling, and advanced visualization capabilities with support for both NetworkX/matplotlib and GraphViz renderers.

Key Features:

• Parameter Management: Comprehensive geometry cutoffs dialog with tabbed interface for different interaction types

• Preset System: Full preset management with Settings → Manage Presets interface

• PDB Fixing: Integrated structure enhancement dialog with OpenBabel and PDBFixer support

• Visualization: Advanced graph rendering with multiple backend support

Core Components

Main Window

The primary GUI window with updated menu structure:

• File Menu: PDB file operations and recent files

• Settings Menu: - Geometry Cutoffs: Configure interaction parameters - Manage Presets: Access preset management system - PDB Fixing Options: Structure enhancement settings - GraphViz Preferences: Visualization settings

• Analysis Tools: Run analysis and view results

• Visualization: Integrated graph rendering and export

Main GUI window for HBAT application.

This module provides the main tkinter interface for the HBAT application, allowing users to load PDB files, configure analysis parameters, and view results.

class hbat.gui.main_window.MainWindow

Bases: object

Main application window for HBAT.

This class provides the primary GUI interface for HBAT, including file loading, parameter configuration, analysis execution, and results visualization.

Parameters:

None – This class takes no parameters during initialization

__init__() → None

Initialize the main window.

Sets up the complete GUI interface including menus, toolbar, main content area, and status bar.

Returns:

None

Return type:

None

run() → None

Start the GUI application.

Enters the main GUI event loop to begin accepting user interactions. This method blocks until the application is closed.

Returns:

None

Return type:

None

Dialog Components

HBAT provides specialized dialog components for comprehensive parameter management and configuration.

Geometry Cutoffs Dialog

Provides tabbed interface for configuring molecular interaction parameters including:

• Hydrogen Bonds: Classical strong interactions (N/O-H···O/N)

• Weak Hydrogen Bonds: C-H···O interactions for binding analysis

• Halogen Bonds: C-X···A interactions with 150° default angle

• π Interactions: Multiple subtypes including hydrogen-π and halogen-π interactions

• General Parameters: Analysis mode and covalent bond detection

Geometry cutoffs configuration dialog for HBAT GUI.

This module provides a dialog for configuring molecular interaction analysis parameters (distances, angles, etc.) without PDB fixing options.

class hbat.gui.geometry_cutoffs_dialog.GeometryCutoffsDialog(parent: tkinter.Tk, current_params: AnalysisParameters | None = None)

Bases: object

Dialog for configuring comprehensive molecular interaction parameters.

Provides GUI interface for setting parameters for multiple interaction types:

• Hydrogen Bonds: Classical strong interactions (N/O-H···O/N)

• Weak Hydrogen Bonds: C-H···O interactions (important for binding)

• Halogen Bonds: C-X···A interactions (X = Cl, Br, I) with 150° default

• π Interactions: Multiple subtypes including:

  • Hydrogen-π: C-H···π, N-H···π, O-H···π, S-H···π

  • Halogen-π: C-Cl···π, C-Br···π, C-I···π

Uses tabbed interface to organize parameters by interaction type.

__init__(parent: tkinter.Tk, current_params: AnalysisParameters | None = None)

Initialize geometry cutoffs dialog.

Parameters:

• parent (tk.Tk) – Parent window

• current_params (Optional[AnalysisParameters]) – Current analysis parameters

get_parameters() → AnalysisParameters

Get current parameter values.

Returns:

Current analysis parameters

Return type:

AnalysisParameters

set_parameters(params: AnalysisParameters) → None

Set parameter values from AnalysisParameters object.

Parameters:

params (AnalysisParameters) – Analysis parameters to set

reset_to_defaults() → None

Public method to reset parameters to defaults.

get_result() → AnalysisParameters | None

Get the configured parameters.

Returns:

Analysis parameters or None if cancelled

Return type:

Optional[AnalysisParameters]

Preset Manager Dialog

Manages parameter presets through Settings → Manage Presets menu:

• Load Presets: Apply built-in or custom parameter sets

• Save Presets: Store current parameter configurations

• Delete Presets: Remove custom presets (built-in presets protected)

• Preset Validation: Automatic parameter validation and error checking

Preset Manager dialog for HBAT GUI.

This module provides a dedicated dialog for managing analysis parameter presets, including loading, saving, and organizing preset files.

class hbat.gui.preset_manager_dialog.PresetManagerDialog(parent: tkinter.Tk, current_params: AnalysisParameters | None = None)

Bases: object

Dialog for managing analysis parameter presets.

__init__(parent: tkinter.Tk, current_params: AnalysisParameters | None = None)

Initialize preset manager dialog.

Parameters:

• parent (tk.Tk) – Parent window

• current_params (Optional[AnalysisParameters]) – Current analysis parameters

get_result() → Dict[str, Any] | None

Get the dialog result.

Returns:

Selected preset data or None if cancelled

Return type:

Optional[Dict[str, Any]]

PDB Fixing Dialog

Configures structure enhancement options:

• Method Selection: OpenBabel vs PDBFixer (default: PDBFixer)

• Hydrogen Addition: Add missing hydrogen atoms

• Heavy Atom Completion: Add missing heavy atoms (PDBFixer only)

• Structure Cleaning: Handle non-standard residues and heterogens

PDB Fixing configuration dialog for HBAT GUI.

This module provides a dedicated dialog for configuring PDB fixing parameters, separate from the main geometry parameter settings.

class hbat.gui.pdb_fixing_dialog.PDBFixingDialog(parent: tkinter.Tk)

Bases: object

Dialog for configuring PDB fixing parameters.

__init__(parent: tkinter.Tk)

Initialize PDB fixing dialog.

Parameters:

parent (tk.Tk) – Parent window

get_parameters() → Dict[str, Any] | None

Get the configured parameters.

Returns:

Dictionary of PDB fixing parameters or None if cancelled

Return type:

Optional[Dict[str, Any]]

set_parameters(params: Dict[str, Any])

Set parameters from a dictionary.

Parameters:

params (Dict[str, Any]) – Dictionary of PDB fixing parameters

Results Panel

Displays comprehensive analysis results with enhanced interaction type support:

• Hydrogen Bonds: Classical and weak (C-H···O) interactions

• Halogen Bonds: With updated 150° default angle detection

• π Interactions: All subtypes (C-H···π, N-H···π, O-H···π, S-H···π, C-Cl···π, C-Br···π, C-I···π)

• Cooperativity Chains: Linked interaction networks

• Export Options: CSV, JSON, and formatted text output

Results display panel for HBAT analysis.

This module provides GUI components for displaying analysis results including hydrogen bonds, halogen bonds, and π interactions.

class hbat.gui.results_panel.ResultsPanel(parent)

Bases: object

Panel for displaying analysis results.

This class provides a tabbed interface for viewing different types of molecular interaction results including summaries, detailed lists, and statistical analysis.

Parameters:

parent (tkinter widget) – Parent widget to contain this panel

__init__(parent) → None

Initialize the results panel.

Creates a complete results display interface with multiple tabs for different views of analysis results.

Parameters:

parent (tkinter widget) – Parent widget

Returns:

None

Return type:

None

update_results(analyzer: NPMolecularInteractionAnalyzer) → None

Update the results panel with new analysis results.

Refreshes all result displays with data from the provided analyzer instance.

Parameters:

analyzer (MolecularInteractionAnalyzer) – MolecularInteractionAnalyzer instance with results

Returns:

None

Return type:

None

clear_results() → None

Clear all results from the panel.

Removes all displayed results and resets the panel to its initial empty state.

Returns:

None

Return type:

None

Chain Visualization

Visualization of cooperativity chains and interaction networks with support for the expanded interaction types.

Chain visualization window for HBAT cooperative hydrogen bond analysis.

This module provides a dedicated window for visualizing cooperative hydrogen bond chains using NetworkX and matplotlib with ellipse-shaped nodes.

class hbat.gui.chain_visualization.ChainVisualizationWindow(parent, chain, chain_id, config: HBATConfig | None = None)

Bases: object

Window for visualizing cooperative hydrogen bond chains.

This class creates a dedicated visualization window for displaying cooperative interaction chains using NetworkX graphs and matplotlib.

Parameters:

• parent (tkinter widget) – Parent widget

• chain (CooperativityChain) – CooperativityChain object to visualize

• chain_id (str) – String identifier for the chain

__init__(parent, chain, chain_id, config: HBATConfig | None = None) → None

Initialize the chain visualization window.

Sets up the visualization window with NetworkX graph rendering capabilities for displaying cooperative interaction chains.

Parameters:

• parent (tkinter widget) – Parent widget

• chain (CooperativityChain) – CooperativityChain object to visualize

• chain_id (str) – String identifier for the chain

• config (Optional[HBATConfig]) – HBAT configuration instance (optional)

Returns:

None

Return type:

None

Visualization System

The visualization system provides a flexible renderer architecture with support for multiple backends, enhanced to handle the expanded set of molecular interactions including π interaction subtypes and weak hydrogen bonds.

Visualization Renderer Protocol

Visualization renderer protocol and base classes for HBAT.

This module defines the interface and common functionality for different visualization renderers (GraphViz, matplotlib) used in cooperative chain visualization.

class hbat.gui.visualization_renderer.VisualizationRenderer(*args, **kwargs)

Bases: Protocol

Protocol for visualization renderer implementations.

This protocol defines the interface that all visualization renderers must implement to be compatible with the chain visualization system.

render(graph: Graph, layout_type: str) → None

Render the graph with the specified layout.

Parameters:

• graph (nx.Graph) – NetworkX graph to render

• layout_type (str) – Layout algorithm name

Returns:

None

Return type:

None

export(format: str, filename: str) → bool

Export visualization to file.

Parameters:

• format (str) – Export format (png, svg, pdf, etc.)

• filename (str) – Output filename

Returns:

True if export successful, False otherwise

Return type:

bool

update_layout(layout_type: str) → None

Update visualization with new layout.

Parameters:

layout_type (str) – New layout algorithm name

Returns:

None

Return type:

None

get_supported_formats() → List[str]

Get list of supported export formats.

Returns:

List of supported format names

Return type:

List[str]

get_supported_layouts() → List[str]

Get list of supported layout algorithms.

Returns:

List of supported layout names

Return type:

List[str]

is_available() → bool

Check if renderer is available for use.

Returns:

True if renderer can be used

Return type:

bool

get_renderer_name() → str

Get human-readable name of the renderer.

Returns:

Renderer name

Return type:

str

__init__(*args, **kwargs)

class hbat.gui.visualization_renderer.BaseVisualizationRenderer(parent_widget: tkinter.Widget, config: HBATConfig)

Bases: ABC

Abstract base class for visualization renderers.

Provides common functionality and enforces the VisualizationRenderer protocol implementation.

__init__(parent_widget: tkinter.Widget, config: HBATConfig) → None

Initialize the base renderer.

Parameters:

• parent_widget (tk.Widget) – Parent tkinter widget

• config (HBATConfig) – HBAT configuration instance

abstractmethod render(graph: Graph, layout_type: str) → None

Render the graph with the specified layout.

Must be implemented by subclasses.

abstractmethod export(format: str, filename: str) → bool

Export visualization to file.

Must be implemented by subclasses.

abstractmethod get_supported_formats() → List[str]

Get list of supported export formats.

Must be implemented by subclasses.

abstractmethod is_available() → bool

Check if renderer is available for use.

Must be implemented by subclasses.

abstractmethod get_renderer_name() → str

Get human-readable name of the renderer.

Must be implemented by subclasses.

update_layout(layout_type: str) → None

Update visualization with new layout.

Default implementation re-renders with new layout.

Parameters:

layout_type (str) – New layout algorithm name

get_supported_layouts() → List[str]

Get list of supported layout algorithms.

Default implementation returns common layouts.

Returns:

List of supported layout names

Return type:

List[str]

prepare_graph_data(graph: Graph) → None

Prepare node and edge data for rendering.

This method extracts styling information from the NetworkX graph and prepares it for rendering.

Parameters:

graph (nx.Graph) – NetworkX graph to prepare

validate_layout(layout_type: str) → bool

Validate if layout type is supported.

Parameters:

layout_type (str) – Layout type to validate

Returns:

True if layout is supported

Return type:

bool

get_last_export_path() → str | None

Get the path of the last successful export.

Returns:

Last export path or None

Return type:

Optional[str]

set_last_export_path(path: str) → None

Set the path of the last successful export.

Parameters:

path (str) – Export path to remember

class hbat.gui.visualization_renderer.RendererFactory

Bases: object

Factory class for creating visualization renderers.

Handles selection and instantiation of appropriate renderers based on availability and user preferences.

static create_renderer(parent_widget: tkinter.Widget, config: HBATConfig, preferred_type: str | None = None) → VisualizationRenderer

Create appropriate visualization renderer.

Parameters:

• parent_widget (tk.Widget) – Parent tkinter widget

• config (HBATConfig) – HBAT configuration instance

• preferred_type (Optional[str]) – Preferred renderer type (“graphviz” or “matplotlib”)

Returns:

Visualization renderer instance

Return type:

VisualizationRenderer

Raises:

ImportError – If no renderer is available

static get_available_renderers(config: HBATConfig) → List[Tuple[str, str]]

Get list of available renderers.

Parameters:

config (HBATConfig) – HBAT configuration instance

Returns:

List of (renderer_type, renderer_name) tuples

Return type:

List[Tuple[str, str]]

GraphViz Renderer

Advanced graph rendering with support for all interaction types and enhanced visual styling:

• Node Styling: Residue-based coloring and labeling

• Edge Types: Different styles for hydrogen bonds, halogen bonds, π interactions

• Interaction Labeling: Display interaction types (C-H···π, C-Cl···π, etc.)

• Export Formats: PNG, SVG, PDF with configurable DPI

GraphViz-based visualization renderer for HBAT.

This module implements the VisualizationRenderer protocol using GraphViz for high-quality rendering of cooperative hydrogen bond chains.

class hbat.gui.graphviz_renderer.GraphVizRenderer(parent_widget: tkinter.Widget, config: HBATConfig)

Bases: BaseVisualizationRenderer

GraphViz-based visualization renderer.

Implements high-quality graph rendering using GraphViz layout engines with fallback to subprocess calls if the Python graphviz package is not available.

__init__(parent_widget: tkinter.Widget, config: HBATConfig) → None

Initialize GraphViz renderer.

Parameters:

• parent_widget (tk.Widget) – Parent tkinter widget

• config (HBATConfig) – HBAT configuration instance

render(graph: Graph, layout_type: str) → None

Render the graph using GraphViz.

Parameters:

• graph (nx.Graph) – NetworkX graph to render

• layout_type (str) – Layout algorithm name

export(format: str, filename: str) → bool

Export visualization to file.

Parameters:

• format (str) – Export format (png, svg, pdf)

• filename (str) – Output filename

Returns:

True if export successful

Return type:

bool

get_supported_formats() → List[str]

Get list of supported export formats.

Returns:

List of supported format names

Return type:

List[str]

get_supported_layouts() → List[str]

Get list of supported layout algorithms.

Returns:

List of supported layout names

Return type:

List[str]

is_available() → bool

Check if GraphViz renderer is available.

Returns:

True if renderer can be used

Return type:

bool

get_renderer_name() → str

Get human-readable name of the renderer.

Returns:

Renderer name

Return type:

str

generate_dot(graph: Graph, layout_type: str) → str

Generate DOT format string from NetworkX graph.

Parameters:

• graph (nx.Graph) – NetworkX graph to convert

• layout_type (str) – Layout type for engine selection

Returns:

DOT format string

Return type:

str

render_with_graphviz(dot_string: str, layout_type: str) → Image | None

Render DOT string using GraphViz.

Parameters:

• dot_string (str) – DOT format graph description

• layout_type (str) – Layout type for engine selection

Returns:

PIL Image if successful

Return type:

Optional[Image.Image]

cleanup() → None

Clean up temporary files and resources.

__del__() → None

Destructor to ensure cleanup.

Matplotlib Renderer

Matplotlib-based visualization renderer for HBAT.

This module implements the VisualizationRenderer protocol using NetworkX and matplotlib for backward compatibility with existing visualizations.

class hbat.gui.matplotlib_renderer.MatplotlibRenderer(parent_widget: tkinter.Widget, config: HBATConfig)

Bases: BaseVisualizationRenderer

Matplotlib-based visualization renderer.

Provides NetworkX/matplotlib rendering with existing functionality and styling, refactored to use the VisualizationRenderer interface.

__init__(parent_widget: tkinter.Widget, config: HBATConfig) → None

Initialize matplotlib renderer.

Parameters:

• parent_widget (tk.Widget) – Parent tkinter widget

• config (HBATConfig) – HBAT configuration instance

render(graph: Graph, layout_type: str) → None

Render the graph using matplotlib.

Parameters:

• graph (nx.Graph) – NetworkX graph to render

• layout_type (str) – Layout algorithm name

export(format: str, filename: str) → bool

Export visualization to file.

Parameters:

• format (str) – Export format (png, svg, pdf)

• filename (str) – Output filename

Returns:

True if export successful

Return type:

bool

get_supported_formats() → List[str]

Get list of supported export formats.

Returns:

List of supported format names

Return type:

List[str]

is_available() → bool

Check if matplotlib renderer is available.

Returns:

True if renderer can be used

Return type:

bool

get_renderer_name() → str

Get human-readable name of the renderer.

Returns:

Renderer name

Return type:

str

get_canvas() → matplotlib.backends.backend_tkagg.FigureCanvasTkAgg | None

Get the matplotlib canvas widget.

Returns:

Canvas widget for embedding in GUI

Return type:

Optional[FigureCanvasTkAgg]

update_layout(layout_type: str) → None

Update visualization with new layout.

Parameters:

layout_type (str) – New layout algorithm name

get_figure() → matplotlib.figure.Figure | None

Get the matplotlib figure.

Returns:

Matplotlib figure instance

Return type:

Optional[Figure]

clear() → None

Clear the current visualization.

set_title(title: str) → None

Set the plot title.

Parameters:

title (str) – Title text

Export Manager

Handles export of analysis results and visualizations with support for new interaction types:

• Data Export: CSV, JSON formats with all interaction subtypes

• Graph Export: Multiple image formats via GraphViz

• Batch Export: Automatic file generation for each interaction type

• Format Options: Configurable output parameters

Export manager for HBAT visualizations.

This module provides centralized export functionality for different visualization renderers, handling file dialogs, format selection, and export operations.

class hbat.gui.export_manager.ExportManager(renderer: VisualizationRenderer, config: HBATConfig)

Bases: object

Manages visualization export functionality.

Provides a unified interface for exporting visualizations from different renderers with format selection, quality settings, and file management.

__init__(renderer: VisualizationRenderer, config: HBATConfig) → None

Initialize export manager.

Parameters:

• renderer (VisualizationRenderer) – Visualization renderer instance

• config (HBATConfig) – HBAT configuration instance

export_visualization(filename: str | None = None, format: str | None = None, resolution: int | None = None) → bool

Export visualization to file.

If filename or format are not provided, shows dialog to get them.

Parameters:

• filename (Optional[str]) – Output filename (optional)

• format (Optional[str]) – Export format (optional)

• resolution (Optional[int]) – Export resolution/DPI (optional)

Returns:

True if export successful

Return type:

bool

show_export_dialog() → Tuple[str, str] | None

Show export dialog to get filename and format.

Returns:

Tuple of (filename, format) or None if cancelled

Return type:

Optional[Tuple[str, str]]

get_supported_formats() → List[str]

Get list of supported export formats.

Returns:

List of supported format names

Return type:

List[str]

get_format_info(format: str) → Dict[str, any] | None

Get information about an export format.

Parameters:

format (str) – Format name

Returns:

Format information dictionary

Return type:

Optional[Dict[str, any]]

class hbat.gui.export_manager.ExportDialog(supported_formats: List[str], config: HBATConfig, initial_directory: str | None = None)

Bases: object

Dialog for selecting export options.

Provides a GUI for selecting export format, filename, and quality settings.

__init__(supported_formats: List[str], config: HBATConfig, initial_directory: str | None = None) → None

Initialize export dialog.

Parameters:

• supported_formats (List[str]) – List of supported format names

• config (HBATConfig) – HBAT configuration instance

• initial_directory (Optional[str]) – Initial directory for file dialog

show() → Tuple[str, str] | None

Show the export dialog.

Returns:

Tuple of (filename, format) or None if cancelled

Return type:

Optional[Tuple[str, str]]

hbat.gui.export_manager.show_quick_export_dialog(renderer: VisualizationRenderer, config: HBATConfig) → bool

Show a quick export dialog for immediate export.

Parameters:

• renderer (VisualizationRenderer) – Visualization renderer

• config (HBATConfig) – HBAT configuration instance

Returns:

True if export successful

Return type:

bool

GraphViz Preferences Dialog

Configures GraphViz rendering options accessible via Settings → GraphViz Preferences:

• Engine Selection: Choose GraphViz layout engine (dot, neato, circo, etc.)

• Output Format: PNG, SVG, PDF export options

• DPI Settings: Configure resolution for image exports

• Visual Styling: Node and edge appearance options

GraphViz preferences dialog for HBAT.

This module provides a dialog window for configuring GraphViz visualization settings including engine selection, rendering options, and export preferences.

class hbat.gui.graphviz_preferences_dialog.GraphVizPreferencesDialog(parent: tkinter.Widget, config: HBATConfig)

Bases: object

Dialog for configuring GraphViz preferences.

Provides a user interface for setting GraphViz engine preferences, rendering options, and export settings.

__init__(parent: tkinter.Widget, config: HBATConfig) → None

Initialize GraphViz preferences dialog.

Parameters:

• parent (tk.Widget) – Parent widget

• config (HBATConfig) – HBAT configuration instance

show() → bool

Show dialog and wait for result.

Returns:

True if preferences were saved, False if cancelled

Return type:

bool

hbat.gui.graphviz_preferences_dialog.show_graphviz_preferences(parent: tkinter.Widget, config: HBATConfig) → bool

Show GraphViz preferences dialog.

Parameters:

• parent (tk.Widget) – Parent widget

• config (HBATConfig) – HBAT configuration instance

Returns:

True if preferences were saved

Return type:

bool