Core Analysis Engine

The core module contains the main analysis algorithms and data structures.

Analysis Module

Core analysis engine for hydrogen bond and molecular interaction analysis.

This module implements the main computational logic for detecting and analyzing molecular interactions including hydrogen bonds, halogen bonds, and X-H…π interactions.

class hbat.core.analysis.MolecularInteraction[source]

Bases: ABC

Base class for all molecular interactions.

This abstract base class defines the interface for all types of molecular interactions analyzed by HBAT, including hydrogen bonds, halogen bonds, and π interactions.

abstractmethod get_donor_atom() → Atom | None[source]

Get the donor atom if applicable.

Returns:: The donor atom in the interaction, or None if not applicable
Return type:: Optional[Atom]

abstractmethod get_acceptor_atom() → Atom | None[source]

Get the acceptor atom if applicable.

Returns:: The acceptor atom in the interaction, or None if not applicable
Return type:: Optional[Atom]

abstractmethod get_donor_residue() → str[source]

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

abstractmethod get_acceptor_residue() → str[source]

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

abstract property distance: float

Get the interaction distance.

Returns:: Distance between interacting atoms in Angstroms
Return type:: float

abstract property angle: float

Get the interaction angle.

Returns:: Interaction angle in radians
Return type:: float

abstract property interaction_type: str

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

class hbat.core.analysis.HydrogenBond(donor: Atom, hydrogen: Atom, acceptor: Atom, distance: float, angle: float, donor_acceptor_distance: float, bond_type: str, donor_residue: str, acceptor_residue: str)[source]

Bases: object

Represents a hydrogen bond interaction.

This class stores all information about a detected hydrogen bond, including the participating atoms, geometric parameters, and classification information.

Parameters:

donor (Atom) – The hydrogen bond donor atom
hydrogen (Atom) – The hydrogen atom in the bond
acceptor (Atom) – The hydrogen bond acceptor atom
distance (float) – H…A distance in Angstroms
angle (float) – D-H…A angle in radians
donor_acceptor_distance (float) – D…A distance in Angstroms
bond_type (str) – Classification of the hydrogen bond type
donor_residue (str) – Identifier for donor residue
acceptor_residue (str) – Identifier for acceptor residue

donor: Atom

hydrogen: Atom

acceptor: Atom

distance: float

angle: float

donor_acceptor_distance: float

bond_type: str

donor_residue: str

acceptor_residue: str

get_donor_atom() → Atom | None[source]

get_acceptor_atom() → Atom | None[source]

get_donor_residue() → str[source]

get_acceptor_residue() → str[source]

property interaction_type: str

__init__(donor: Atom, hydrogen: Atom, acceptor: Atom, distance: float, angle: float, donor_acceptor_distance: float, bond_type: str, donor_residue: str, acceptor_residue: str) → None

class hbat.core.analysis.HalogenBond(halogen: Atom, acceptor: Atom, distance: float, angle: float, bond_type: str, halogen_residue: str, acceptor_residue: str)[source]

Bases: object

Represents a halogen bond interaction.

This class stores information about a detected halogen bond, where a halogen atom acts as an electron acceptor.

Parameters:

halogen (Atom) – The halogen atom (F, Cl, Br, I)
acceptor (Atom) – The electron donor/acceptor atom
distance (float) – X…A distance in Angstroms
angle (float) – C-X…A angle in radians
bond_type (str) – Classification of the halogen bond type
halogen_residue (str) – Identifier for halogen-containing residue
acceptor_residue (str) – Identifier for acceptor residue

halogen: Atom

acceptor: Atom

distance: float

angle: float

bond_type: str

halogen_residue: str

acceptor_residue: str

get_donor_atom() → Atom | None[source]

get_acceptor_atom() → Atom | None[source]

get_donor_residue() → str[source]

get_acceptor_residue() → str[source]

property interaction_type: str

__init__(halogen: Atom, acceptor: Atom, distance: float, angle: float, bond_type: str, halogen_residue: str, acceptor_residue: str) → None

class hbat.core.analysis.PiInteraction(donor: Atom, hydrogen: Atom, pi_center: Vec3D, distance: float, angle: float, donor_residue: str, pi_residue: str)[source]

Bases: object

Represents an X-H…π interaction.

This class stores information about a detected X-H…π interaction, where a hydrogen bond donor interacts with an aromatic π system.

Parameters:

donor (Atom) – The hydrogen bond donor atom
hydrogen (Atom) – The hydrogen atom
pi_center (Vec3D) – Center of the aromatic π system
distance (float) – H…π distance in Angstroms
angle (float) – D-H…π angle in radians
donor_residue (str) – Identifier for donor residue
pi_residue (str) – Identifier for π-containing residue

donor: Atom

hydrogen: Atom

pi_center: Vec3D

distance: float

angle: float

donor_residue: str

pi_residue: str

get_donor_atom() → Atom | None[source]

get_acceptor_atom() → Atom | None[source]

get_donor_residue() → str[source]

get_acceptor_residue() → str[source]

property interaction_type: str

__init__(donor: Atom, hydrogen: Atom, pi_center: Vec3D, distance: float, angle: float, donor_residue: str, pi_residue: str) → None

class hbat.core.analysis.CooperativityChain(interactions: List[HydrogenBond | HalogenBond | PiInteraction], chain_length: int, chain_type: str)[source]

Bases: object

Represents a chain of cooperative molecular interactions.

This class represents a series of linked molecular interactions where the acceptor of one interaction acts as the donor of the next, creating cooperative effects.

Parameters:

interactions (List[Union[HydrogenBond, HalogenBond, PiInteraction]]) – List of interactions in the chain
chain_length (int) – Number of interactions in the chain
chain_type (str) – Description of the interaction types in the chain

interactions: List[HydrogenBond | HalogenBond | PiInteraction]

chain_length: int

chain_type: str

__init__(interactions: List[HydrogenBond | HalogenBond | PiInteraction], chain_length: int, chain_type: str) → None

class hbat.core.analysis.AnalysisParameters(hb_distance_cutoff: float = 3.5, hb_angle_cutoff: float = 120.0, hb_donor_acceptor_cutoff: float = 4.0, xb_distance_cutoff: float = 4.0, xb_angle_cutoff: float = 120.0, pi_distance_cutoff: float = 4.5, pi_angle_cutoff: float = 90.0, covalent_cutoff_factor: float = 1.2, analysis_mode: str = 'complete')[source]

Bases: object

Parameters for molecular interaction analysis.

This class contains all configurable parameters used during molecular interaction analysis, including distance cutoffs, angle thresholds, and analysis modes.

Parameters:

hb_distance_cutoff (float) – Maximum H…A distance for hydrogen bonds (Å)
hb_angle_cutoff (float) – Minimum D-H…A angle for hydrogen bonds (degrees)
hb_donor_acceptor_cutoff (float) – Maximum D…A distance for hydrogen bonds (Å)
xb_distance_cutoff (float) – Maximum X…A distance for halogen bonds (Å)
xb_angle_cutoff (float) – Minimum C-X…A angle for halogen bonds (degrees)
pi_distance_cutoff (float) – Maximum H…π distance for π interactions (Å)
pi_angle_cutoff (float) – Minimum D-H…π angle for π interactions (degrees)
covalent_cutoff_factor (float) – Factor for covalent bond detection
analysis_mode (str) – Analysis mode (‘local’ or ‘global’)

hb_distance_cutoff: float = 3.5

hb_angle_cutoff: float = 120.0

hb_donor_acceptor_cutoff: float = 4.0

xb_distance_cutoff: float = 4.0

xb_angle_cutoff: float = 120.0

pi_distance_cutoff: float = 4.5

pi_angle_cutoff: float = 90.0

covalent_cutoff_factor: float = 1.2

analysis_mode: str = 'complete'

__init__(hb_distance_cutoff: float = 3.5, hb_angle_cutoff: float = 120.0, hb_donor_acceptor_cutoff: float = 4.0, xb_distance_cutoff: float = 4.0, xb_angle_cutoff: float = 120.0, pi_distance_cutoff: float = 4.5, pi_angle_cutoff: float = 90.0, covalent_cutoff_factor: float = 1.2, analysis_mode: str = 'complete') → None

class hbat.core.analysis.HBondAnalyzer(parameters: AnalysisParameters | None = None)[source]

Bases: object

Main analyzer for molecular interactions.

This is the primary class for analyzing molecular interactions in protein structures. It detects hydrogen bonds, halogen bonds, π interactions, and cooperative interaction chains.

Parameters:: parameters (Optional[AnalysisParameters]) – Analysis parameters to use

__init__(parameters: AnalysisParameters | None = None)[source]

Initialize analyzer with parameters.

Parameters:: parameters (Optional[AnalysisParameters]) – Analysis parameters, defaults to standard parameters if None

analyze_file(pdb_file: str) → bool[source]

Analyze a PDB file for molecular interactions.

This method parses a PDB file and analyzes it for all types of molecular interactions supported by HBAT. Results are stored in the analyzer instance for later retrieval.

Parameters:: pdb_file (str) – Path to the PDB file to analyze
Returns:: True if analysis completed successfully, False otherwise
Return type:: bool
Raises:: IOError if file cannot be read

get_statistics() → Dict[str, Any][source]

Get comprehensive analysis statistics.

Returns a dictionary containing counts, averages, and other statistical measures for all detected interactions.

Returns:: Dictionary containing analysis statistics
Return type:: Dict[str, Any]

get_results_summary() → str[source]

Get formatted summary of analysis results.

Returns a human-readable string summarizing all detected interactions and cooperative chains.

Returns:: Formatted string summary of results
Return type:: str

Classes

class hbat.core.analysis.HBondAnalyzer(parameters: AnalysisParameters | None = None)[source]

Bases: object

Main analyzer for molecular interactions.

This is the primary class for analyzing molecular interactions in protein structures. It detects hydrogen bonds, halogen bonds, π interactions, and cooperative interaction chains.

Parameters:: parameters (Optional[AnalysisParameters]) – Analysis parameters to use

__init__(parameters: AnalysisParameters | None = None)[source]

Initialize analyzer with parameters.

Parameters:: parameters (Optional[AnalysisParameters]) – Analysis parameters, defaults to standard parameters if None

analyze_file(pdb_file: str) → bool[source]

Analyze a PDB file for molecular interactions.

This method parses a PDB file and analyzes it for all types of molecular interactions supported by HBAT. Results are stored in the analyzer instance for later retrieval.

Parameters:: pdb_file (str) – Path to the PDB file to analyze
Returns:: True if analysis completed successfully, False otherwise
Return type:: bool
Raises:: IOError if file cannot be read

get_statistics() → Dict[str, Any][source]

Get comprehensive analysis statistics.

Returns a dictionary containing counts, averages, and other statistical measures for all detected interactions.

Returns:: Dictionary containing analysis statistics
Return type:: Dict[str, Any]

get_results_summary() → str[source]

Get formatted summary of analysis results.

Returns a human-readable string summarizing all detected interactions and cooperative chains.

Returns:: Formatted string summary of results
Return type:: str

class hbat.core.analysis.AnalysisParameters(hb_distance_cutoff: float = 3.5, hb_angle_cutoff: float = 120.0, hb_donor_acceptor_cutoff: float = 4.0, xb_distance_cutoff: float = 4.0, xb_angle_cutoff: float = 120.0, pi_distance_cutoff: float = 4.5, pi_angle_cutoff: float = 90.0, covalent_cutoff_factor: float = 1.2, analysis_mode: str = 'complete')[source]

Bases: object

Parameters for molecular interaction analysis.

This class contains all configurable parameters used during molecular interaction analysis, including distance cutoffs, angle thresholds, and analysis modes.

Parameters:

hb_distance_cutoff (float) – Maximum H…A distance for hydrogen bonds (Å)
hb_angle_cutoff (float) – Minimum D-H…A angle for hydrogen bonds (degrees)
hb_donor_acceptor_cutoff (float) – Maximum D…A distance for hydrogen bonds (Å)
xb_distance_cutoff (float) – Maximum X…A distance for halogen bonds (Å)
xb_angle_cutoff (float) – Minimum C-X…A angle for halogen bonds (degrees)
pi_distance_cutoff (float) – Maximum H…π distance for π interactions (Å)
pi_angle_cutoff (float) – Minimum D-H…π angle for π interactions (degrees)
covalent_cutoff_factor (float) – Factor for covalent bond detection
analysis_mode (str) – Analysis mode (‘local’ or ‘global’)

hb_distance_cutoff: float = 3.5

hb_angle_cutoff: float = 120.0

hb_donor_acceptor_cutoff: float = 4.0

xb_distance_cutoff: float = 4.0

xb_angle_cutoff: float = 120.0

pi_distance_cutoff: float = 4.5

pi_angle_cutoff: float = 90.0

covalent_cutoff_factor: float = 1.2

analysis_mode: str = 'complete'

__init__(hb_distance_cutoff: float = 3.5, hb_angle_cutoff: float = 120.0, hb_donor_acceptor_cutoff: float = 4.0, xb_distance_cutoff: float = 4.0, xb_angle_cutoff: float = 120.0, pi_distance_cutoff: float = 4.5, pi_angle_cutoff: float = 90.0, covalent_cutoff_factor: float = 1.2, analysis_mode: str = 'complete') → None

Interaction Classes

class hbat.core.analysis.MolecularInteraction[source]

Bases: ABC

Base class for all molecular interactions.

This abstract base class defines the interface for all types of molecular interactions analyzed by HBAT, including hydrogen bonds, halogen bonds, and π interactions.

abstractmethod get_donor_atom() → Atom | None[source]

Get the donor atom if applicable.

Returns:: The donor atom in the interaction, or None if not applicable
Return type:: Optional[Atom]

abstractmethod get_acceptor_atom() → Atom | None[source]

Get the acceptor atom if applicable.

Returns:: The acceptor atom in the interaction, or None if not applicable
Return type:: Optional[Atom]

abstractmethod get_donor_residue() → str[source]

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

abstractmethod get_acceptor_residue() → str[source]

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

abstract property distance: float

Get the interaction distance.

Returns:: Distance between interacting atoms in Angstroms
Return type:: float

abstract property angle: float

Get the interaction angle.

Returns:: Interaction angle in radians
Return type:: float

abstract property interaction_type: str

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

class hbat.core.analysis.HydrogenBond(donor: Atom, hydrogen: Atom, acceptor: Atom, distance: float, angle: float, donor_acceptor_distance: float, bond_type: str, donor_residue: str, acceptor_residue: str)[source]

Bases: object

Represents a hydrogen bond interaction.

This class stores all information about a detected hydrogen bond, including the participating atoms, geometric parameters, and classification information.

Parameters:

donor (Atom) – The hydrogen bond donor atom
hydrogen (Atom) – The hydrogen atom in the bond
acceptor (Atom) – The hydrogen bond acceptor atom
distance (float) – H…A distance in Angstroms
angle (float) – D-H…A angle in radians
donor_acceptor_distance (float) – D…A distance in Angstroms
bond_type (str) – Classification of the hydrogen bond type
donor_residue (str) – Identifier for donor residue
acceptor_residue (str) – Identifier for acceptor residue

donor: Atom

hydrogen: Atom

acceptor: Atom

distance: float

angle: float

donor_acceptor_distance: float

bond_type: str

donor_residue: str

acceptor_residue: str

get_donor_atom() → Atom | None[source]

get_acceptor_atom() → Atom | None[source]

get_donor_residue() → str[source]

get_acceptor_residue() → str[source]

property interaction_type: str

__init__(donor: Atom, hydrogen: Atom, acceptor: Atom, distance: float, angle: float, donor_acceptor_distance: float, bond_type: str, donor_residue: str, acceptor_residue: str) → None

class hbat.core.analysis.HalogenBond(halogen: Atom, acceptor: Atom, distance: float, angle: float, bond_type: str, halogen_residue: str, acceptor_residue: str)[source]

Bases: object

Represents a halogen bond interaction.

This class stores information about a detected halogen bond, where a halogen atom acts as an electron acceptor.

Parameters:

halogen (Atom) – The halogen atom (F, Cl, Br, I)
acceptor (Atom) – The electron donor/acceptor atom
distance (float) – X…A distance in Angstroms
angle (float) – C-X…A angle in radians
bond_type (str) – Classification of the halogen bond type
halogen_residue (str) – Identifier for halogen-containing residue
acceptor_residue (str) – Identifier for acceptor residue

halogen: Atom

acceptor: Atom

distance: float

angle: float

bond_type: str

halogen_residue: str

acceptor_residue: str

get_donor_atom() → Atom | None[source]

get_acceptor_atom() → Atom | None[source]

get_donor_residue() → str[source]

get_acceptor_residue() → str[source]

property interaction_type: str

__init__(halogen: Atom, acceptor: Atom, distance: float, angle: float, bond_type: str, halogen_residue: str, acceptor_residue: str) → None

class hbat.core.analysis.PiInteraction(donor: Atom, hydrogen: Atom, pi_center: Vec3D, distance: float, angle: float, donor_residue: str, pi_residue: str)[source]

Bases: object

Represents an X-H…π interaction.

This class stores information about a detected X-H…π interaction, where a hydrogen bond donor interacts with an aromatic π system.

Parameters:

donor (Atom) – The hydrogen bond donor atom
hydrogen (Atom) – The hydrogen atom
pi_center (Vec3D) – Center of the aromatic π system
distance (float) – H…π distance in Angstroms
angle (float) – D-H…π angle in radians
donor_residue (str) – Identifier for donor residue
pi_residue (str) – Identifier for π-containing residue

donor: Atom

hydrogen: Atom

pi_center: Vec3D

distance: float

angle: float

donor_residue: str

pi_residue: str

get_donor_atom() → Atom | None[source]

get_acceptor_atom() → Atom | None[source]

get_donor_residue() → str[source]

get_acceptor_residue() → str[source]

property interaction_type: str

__init__(donor: Atom, hydrogen: Atom, pi_center: Vec3D, distance: float, angle: float, donor_residue: str, pi_residue: str) → None

class hbat.core.analysis.CooperativityChain(interactions: List[HydrogenBond | HalogenBond | PiInteraction], chain_length: int, chain_type: str)[source]

Bases: object

Represents a chain of cooperative molecular interactions.

This class represents a series of linked molecular interactions where the acceptor of one interaction acts as the donor of the next, creating cooperative effects.

Parameters:

interactions (List[Union[HydrogenBond, HalogenBond, PiInteraction]]) – List of interactions in the chain
chain_length (int) – Number of interactions in the chain
chain_type (str) – Description of the interaction types in the chain

interactions: List[HydrogenBond | HalogenBond | PiInteraction]

chain_length: int

chain_type: str

__init__(interactions: List[HydrogenBond | HalogenBond | PiInteraction], chain_length: int, chain_type: str) → None

PDB Parser Module

PDB file parser for molecular structure analysis using pdbreader.

This module provides functionality to parse PDB (Protein Data Bank) files and extract atomic coordinates and molecular information using the pdbreader library.

class hbat.core.pdb_parser.Atom(serial: int, name: str, alt_loc: str, res_name: str, chain_id: str, res_seq: int, i_code: str, coords: Vec3D, occupancy: float, temp_factor: float, element: str, charge: str, record_type: str)[source]

Bases: object

Represents an atom from a PDB file.

This class stores all atomic information parsed from PDB format including coordinates, properties, and residue information.

Parameters:

serial (int) – Atom serial number
name (str) – Atom name
alt_loc (str) – Alternate location indicator
res_name (str) – Residue name
chain_id (str) – Chain identifier
res_seq (int) – Residue sequence number
i_code (str) – Insertion code
coords (Vec3D) – 3D coordinates
occupancy (float) – Occupancy factor
temp_factor (float) – Temperature factor
element (str) – Element symbol
charge (str) – Formal charge
record_type (str) – PDB record type (ATOM or HETATM)

serial: int

name: str

alt_loc: str

res_name: str

chain_id: str

res_seq: int

i_code: str

coords: Vec3D

occupancy: float

temp_factor: float

element: str

charge: str

record_type: str

is_hydrogen() → bool[source]

Check if atom is hydrogen.

Returns:: True if atom is hydrogen or deuterium
Return type:: bool

is_metal() → bool[source]

Check if atom is a metal.

Returns:: True if atom is a common metal ion
Return type:: bool

__init__(serial: int, name: str, alt_loc: str, res_name: str, chain_id: str, res_seq: int, i_code: str, coords: Vec3D, occupancy: float, temp_factor: float, element: str, charge: str, record_type: str) → None

class hbat.core.pdb_parser.Residue(name: str, chain_id: str, seq_num: int, i_code: str, atoms: List[Atom])[source]

Bases: object

Represents a residue containing multiple atoms.

This class groups atoms belonging to the same residue and provides methods for accessing and analyzing residue-level information.

Parameters:

name (str) – Residue name (e.g., ‘ALA’, ‘GLY’)
chain_id (str) – Chain identifier
seq_num (int) – Residue sequence number
i_code (str) – Insertion code
atoms (List[Atom]) – List of atoms in this residue

name: str

chain_id: str

seq_num: int

i_code: str

atoms: List[Atom]

get_atom(atom_name: str) → Atom | None[source]

Get specific atom by name.

Parameters:: atom_name (str) – Name of the atom to find
Returns:: The atom if found, None otherwise
Return type:: Optional[Atom]

get_atoms_by_element(element: str) → List[Atom][source]

Get all atoms of specific element.

Parameters:: element (str) – Element symbol (e.g., ‘C’, ‘N’, ‘O’)
Returns:: List of atoms matching the element
Return type:: List[Atom]

center_of_mass() → Vec3D[source]

Calculate center of mass of residue.

Computes the mass-weighted centroid of all atoms in the residue.

Returns:: Center of mass coordinates
Return type:: Vec3D

__init__(name: str, chain_id: str, seq_num: int, i_code: str, atoms: List[Atom]) → None

class hbat.core.pdb_parser.PDBParser[source]

Bases: object

Parser for PDB format files using pdbreader.

This class handles parsing of PDB (Protein Data Bank) format files and converts them into HBAT’s internal atom and residue representations. Uses the pdbreader library for robust PDB format handling.

__init__() → None[source]

Initialize PDB parser.

Creates a new parser instance with empty atom and residue lists.

parse_file(filename: str) → bool[source]

Parse a PDB file.

Reads and parses a PDB format file, extracting all ATOM and HETATM records and converting them to HBAT’s internal representation.

Parameters:: filename (str) – Path to the PDB file to parse
Returns:: True if parsing completed successfully, False otherwise
Return type:: bool
Raises:: IOError if file cannot be read

parse_lines(lines: List[str]) → bool[source]

Parse PDB format lines.

Parses PDB format content provided as a list of strings, useful for processing in-memory PDB data.

Parameters:: lines (List[str]) – List of PDB format lines
Returns:: True if parsing completed successfully, False otherwise
Return type:: bool

get_atoms_by_element(element: str) → List[Atom][source]

Get all atoms of specific element.

Parameters:: element (str) – Element symbol (e.g., ‘C’, ‘N’, ‘O’)
Returns:: List of atoms matching the element
Return type:: List[Atom]

get_atoms_by_residue(res_name: str) → List[Atom][source]

Get all atoms from residues with specific name.

Parameters:: res_name (str) – Residue name (e.g., ‘ALA’, ‘GLY’)
Returns:: List of atoms from matching residues
Return type:: List[Atom]

get_hydrogen_atoms() → List[Atom][source]

Get all hydrogen atoms.

Returns:: List of all hydrogen and deuterium atoms
Return type:: List[Atom]

has_hydrogens() → bool[source]

Check if structure contains hydrogen atoms.

Determines if the structure has a reasonable number of hydrogen atoms compared to heavy atoms, indicating explicit hydrogen modeling.

Returns:: True if structure appears to contain explicit hydrogens
Return type:: bool

get_residue_list() → List[Residue][source]

Get list of all residues.

Returns:: List of all residues in the structure
Return type:: List[Residue]

get_chain_ids() → List[str][source]

Get list of unique chain IDs.

Returns:: List of unique chain identifiers in the structure
Return type:: List[str]

get_statistics() → Dict[str, Any][source]

Get basic statistics about the structure.

Provides counts of atoms, residues, chains, and element composition.

Returns:: Dictionary containing structure statistics
Return type:: Dict[str, Any]

Classes

class hbat.core.pdb_parser.PDBParser[source]

Bases: object

Parser for PDB format files using pdbreader.

This class handles parsing of PDB (Protein Data Bank) format files and converts them into HBAT’s internal atom and residue representations. Uses the pdbreader library for robust PDB format handling.

__init__() → None[source]

Initialize PDB parser.

Creates a new parser instance with empty atom and residue lists.

parse_file(filename: str) → bool[source]

Parse a PDB file.

Reads and parses a PDB format file, extracting all ATOM and HETATM records and converting them to HBAT’s internal representation.

Parameters:: filename (str) – Path to the PDB file to parse
Returns:: True if parsing completed successfully, False otherwise
Return type:: bool
Raises:: IOError if file cannot be read

parse_lines(lines: List[str]) → bool[source]

Parse PDB format lines.

Parses PDB format content provided as a list of strings, useful for processing in-memory PDB data.

Parameters:: lines (List[str]) – List of PDB format lines
Returns:: True if parsing completed successfully, False otherwise
Return type:: bool

get_atoms_by_element(element: str) → List[Atom][source]

Get all atoms of specific element.

Parameters:: element (str) – Element symbol (e.g., ‘C’, ‘N’, ‘O’)
Returns:: List of atoms matching the element
Return type:: List[Atom]

get_atoms_by_residue(res_name: str) → List[Atom][source]

Get all atoms from residues with specific name.

Parameters:: res_name (str) – Residue name (e.g., ‘ALA’, ‘GLY’)
Returns:: List of atoms from matching residues
Return type:: List[Atom]

get_hydrogen_atoms() → List[Atom][source]

Get all hydrogen atoms.

Returns:: List of all hydrogen and deuterium atoms
Return type:: List[Atom]

has_hydrogens() → bool[source]

Check if structure contains hydrogen atoms.

Determines if the structure has a reasonable number of hydrogen atoms compared to heavy atoms, indicating explicit hydrogen modeling.

Returns:: True if structure appears to contain explicit hydrogens
Return type:: bool

get_residue_list() → List[Residue][source]

Get list of all residues.

Returns:: List of all residues in the structure
Return type:: List[Residue]

get_chain_ids() → List[str][source]

Get list of unique chain IDs.

Returns:: List of unique chain identifiers in the structure
Return type:: List[str]

get_statistics() → Dict[str, Any][source]

Get basic statistics about the structure.

Provides counts of atoms, residues, chains, and element composition.

Returns:: Dictionary containing structure statistics
Return type:: Dict[str, Any]

class hbat.core.pdb_parser.Atom(serial: int, name: str, alt_loc: str, res_name: str, chain_id: str, res_seq: int, i_code: str, coords: Vec3D, occupancy: float, temp_factor: float, element: str, charge: str, record_type: str)[source]

Bases: object

Represents an atom from a PDB file.

This class stores all atomic information parsed from PDB format including coordinates, properties, and residue information.

Parameters:

serial (int) – Atom serial number
name (str) – Atom name
alt_loc (str) – Alternate location indicator
res_name (str) – Residue name
chain_id (str) – Chain identifier
res_seq (int) – Residue sequence number
i_code (str) – Insertion code
coords (Vec3D) – 3D coordinates
occupancy (float) – Occupancy factor
temp_factor (float) – Temperature factor
element (str) – Element symbol
charge (str) – Formal charge
record_type (str) – PDB record type (ATOM or HETATM)

serial: int

name: str

alt_loc: str

res_name: str

chain_id: str

res_seq: int

i_code: str

coords: Vec3D

occupancy: float

temp_factor: float

element: str

charge: str

record_type: str

is_hydrogen() → bool[source]

Check if atom is hydrogen.

Returns:: True if atom is hydrogen or deuterium
Return type:: bool

is_metal() → bool[source]

Check if atom is a metal.

Returns:: True if atom is a common metal ion
Return type:: bool

__init__(serial: int, name: str, alt_loc: str, res_name: str, chain_id: str, res_seq: int, i_code: str, coords: Vec3D, occupancy: float, temp_factor: float, element: str, charge: str, record_type: str) → None

class hbat.core.pdb_parser.Residue(name: str, chain_id: str, seq_num: int, i_code: str, atoms: List[Atom])[source]

Bases: object

Represents a residue containing multiple atoms.

This class groups atoms belonging to the same residue and provides methods for accessing and analyzing residue-level information.

Parameters:

name (str) – Residue name (e.g., ‘ALA’, ‘GLY’)
chain_id (str) – Chain identifier
seq_num (int) – Residue sequence number
i_code (str) – Insertion code
atoms (List[Atom]) – List of atoms in this residue

name: str

chain_id: str

seq_num: int

i_code: str

atoms: List[Atom]

get_atom(atom_name: str) → Atom | None[source]

Get specific atom by name.

Parameters:: atom_name (str) – Name of the atom to find
Returns:: The atom if found, None otherwise
Return type:: Optional[Atom]

get_atoms_by_element(element: str) → List[Atom][source]

Get all atoms of specific element.

Parameters:: element (str) – Element symbol (e.g., ‘C’, ‘N’, ‘O’)
Returns:: List of atoms matching the element
Return type:: List[Atom]

center_of_mass() → Vec3D[source]

Calculate center of mass of residue.

Computes the mass-weighted centroid of all atoms in the residue.

Returns:: Center of mass coordinates
Return type:: Vec3D

__init__(name: str, chain_id: str, seq_num: int, i_code: str, atoms: List[Atom]) → None

Vector Mathematics Module

3D Vector mathematics for molecular analysis.

This module provides Vec3D class for 3D vector operations used in molecular geometry calculations.

class hbat.core.vector.Vec3D(x: float = 0.0, y: float = 0.0, z: float = 0.0)[source]

Bases: object

3D vector class for molecular calculations.

This class provides comprehensive 3D vector operations used in molecular geometry calculations, including distance measurements, angle calculations, and coordinate transformations.

Parameters:

x (float) – X coordinate component
y (float) – Y coordinate component
z (float) – Z coordinate component

__init__(x: float = 0.0, y: float = 0.0, z: float = 0.0)[source]

Initialize a 3D vector.

Parameters:

x (float) – X coordinate component
y (float) – Y coordinate component
z (float) – Z coordinate component

__add__(other: Vec3D) → Vec3D[source]: Vector addition.

__sub__(other: Vec3D) → Vec3D[source]: Vector subtraction.

__mul__(scalar: float) → Vec3D[source]: Scalar multiplication.

__rmul__(scalar: float) → Vec3D[source]: Reverse scalar multiplication.

__eq__(other: object) → bool[source]: Vector equality comparison.

__truediv__(scalar: float) → Vec3D[source]: Scalar division.

__getitem__(index: int) → float[source]: Get component by index (0=x, 1=y, 2=z).

__setitem__(index: int, value: float) → None[source]

Set component by index (0=x, 1=y, 2=z).

Parameters:

index (int) – Component index (0=x, 1=y, 2=z)
value (float) – New value for the component

Raises:

IndexError – If index is out of range (not 0, 1, or 2)

Returns:

None

Return type:

None

dot(other: Vec3D) → float[source]

Dot product with another vector.

Parameters:: other (Vec3D) – The other vector
Returns:: Dot product result
Return type:: float

cross(other: Vec3D) → Vec3D[source]

Cross product with another vector.

Parameters:: other (Vec3D) – The other vector
Returns:: Cross product vector
Return type:: Vec3D

length() → float[source]

Calculate vector length/magnitude.

Returns:: Euclidean length of the vector
Return type:: float

magnitude() → float[source]

Alias for length().

Returns:: Euclidean magnitude of the vector
Return type:: float

normalize() → Vec3D[source]

Return normalized unit vector.

Returns:: Unit vector in the same direction
Return type:: Vec3D

unit_vector() → Vec3D[source]

Alias for normalize().

Returns:: Unit vector in the same direction
Return type:: Vec3D

distance_to(other: Vec3D) → float[source]

Calculate distance to another vector.

Parameters:: other (Vec3D) – The target vector
Returns:: Euclidean distance between vectors
Return type:: float

angle_to(other: Vec3D) → float[source]

Calculate angle to another vector in radians.

Parameters:: other (Vec3D) – The target vector
Returns:: Angle between vectors in radians
Return type:: float

to_list() → List[float][source]

Convert to list [x, y, z].

Returns:: Vector components as a list
Return type:: List[float]

to_tuple() → Tuple[float, float, float][source]

Convert to tuple (x, y, z).

Returns:: Vector components as a tuple
Return type:: Tuple[float, float, float]

classmethod from_list(coords: List[float]) → Vec3D[source]

Create vector from list [x, y, z].

Parameters:: coords (List[float]) – List of coordinates [x, y, z]
Returns:: New Vec3D instance
Return type:: Vec3D

classmethod from_tuple(coords: Tuple[float, ...]) → Vec3D[source]

Create vector from tuple (x, y, z).

Parameters:: coords (Tuple[float, ...]) – Tuple of coordinates (x, y, z)
Returns:: New Vec3D instance
Return type:: Vec3D

hbat.core.vector.unit_vector_between(a: Vec3D, b: Vec3D) → Vec3D[source]

Return unit vector pointing from a to b.

Parameters:

a (Vec3D) – Starting point vector
b (Vec3D) – Ending point vector

Returns:

Unit vector pointing from a to b

Return type:

Vec3D

hbat.core.vector.angle_between_vectors(a: Vec3D, b: Vec3D, c: Vec3D | None = None) → float[source]

Calculate angle between vectors.

If c is provided: Calculate angle ABC where B is the vertex. If c is None: Calculate angle between vectors a and b.

Parameters:

a (Vec3D) – First vector or point A
b (Vec3D) – Second vector or vertex point B
c (Vec3D, optional) – Optional third point C for angle ABC

Returns:

Angle in radians

Return type:

float

hbat.core.vector.dihedral_angle(a: Vec3D, b: Vec3D, c: Vec3D, d: Vec3D) → float[source]

Calculate dihedral angle between planes ABC and BCD.

Parameters:

a (Vec3D) – First point defining plane ABC
b (Vec3D) – Second point defining both planes
c (Vec3D) – Third point defining both planes
d (Vec3D) – Fourth point defining plane BCD

Returns:

Dihedral angle in radians

Return type:

float

Classes

class hbat.core.vector.Vec3D(x: float = 0.0, y: float = 0.0, z: float = 0.0)[source]

Bases: object

3D vector class for molecular calculations.

This class provides comprehensive 3D vector operations used in molecular geometry calculations, including distance measurements, angle calculations, and coordinate transformations.

Parameters:

x (float) – X coordinate component
y (float) – Y coordinate component
z (float) – Z coordinate component

__init__(x: float = 0.0, y: float = 0.0, z: float = 0.0)[source]

Initialize a 3D vector.

Parameters:

x (float) – X coordinate component
y (float) – Y coordinate component
z (float) – Z coordinate component

__add__(other: Vec3D) → Vec3D[source]: Vector addition.

__sub__(other: Vec3D) → Vec3D[source]: Vector subtraction.

__mul__(scalar: float) → Vec3D[source]: Scalar multiplication.

__rmul__(scalar: float) → Vec3D[source]: Reverse scalar multiplication.

__eq__(other: object) → bool[source]: Vector equality comparison.

__truediv__(scalar: float) → Vec3D[source]: Scalar division.

__getitem__(index: int) → float[source]: Get component by index (0=x, 1=y, 2=z).

__setitem__(index: int, value: float) → None[source]

Set component by index (0=x, 1=y, 2=z).

Parameters:

index (int) – Component index (0=x, 1=y, 2=z)
value (float) – New value for the component

Raises:

IndexError – If index is out of range (not 0, 1, or 2)

Returns:

None

Return type:

None

dot(other: Vec3D) → float[source]

Dot product with another vector.

Parameters:: other (Vec3D) – The other vector
Returns:: Dot product result
Return type:: float

cross(other: Vec3D) → Vec3D[source]

Cross product with another vector.

Parameters:: other (Vec3D) – The other vector
Returns:: Cross product vector
Return type:: Vec3D

length() → float[source]

Calculate vector length/magnitude.

Returns:: Euclidean length of the vector
Return type:: float

magnitude() → float[source]

Alias for length().

Returns:: Euclidean magnitude of the vector
Return type:: float

normalize() → Vec3D[source]

Return normalized unit vector.

Returns:: Unit vector in the same direction
Return type:: Vec3D

unit_vector() → Vec3D[source]

Alias for normalize().

Returns:: Unit vector in the same direction
Return type:: Vec3D

distance_to(other: Vec3D) → float[source]

Calculate distance to another vector.

Parameters:: other (Vec3D) – The target vector
Returns:: Euclidean distance between vectors
Return type:: float

angle_to(other: Vec3D) → float[source]

Calculate angle to another vector in radians.

Parameters:: other (Vec3D) – The target vector
Returns:: Angle between vectors in radians
Return type:: float

to_list() → List[float][source]

Convert to list [x, y, z].

Returns:: Vector components as a list
Return type:: List[float]

to_tuple() → Tuple[float, float, float][source]

Convert to tuple (x, y, z).

Returns:: Vector components as a tuple
Return type:: Tuple[float, float, float]

classmethod from_list(coords: List[float]) → Vec3D[source]

Create vector from list [x, y, z].

Parameters:: coords (List[float]) – List of coordinates [x, y, z]
Returns:: New Vec3D instance
Return type:: Vec3D

classmethod from_tuple(coords: Tuple[float, ...]) → Vec3D[source]

Create vector from tuple (x, y, z).

Parameters:: coords (Tuple[float, ...]) – Tuple of coordinates (x, y, z)
Returns:: New Vec3D instance
Return type:: Vec3D

Functions

hbat.core.vector.unit_vector_between(a: Vec3D, b: Vec3D) → Vec3D[source]

Return unit vector pointing from a to b.

Parameters:

a (Vec3D) – Starting point vector
b (Vec3D) – Ending point vector

Returns:

Unit vector pointing from a to b

Return type:

Vec3D

hbat.core.vector.angle_between_vectors(a: Vec3D, b: Vec3D, c: Vec3D | None = None) → float[source]

Calculate angle between vectors.

If c is provided: Calculate angle ABC where B is the vertex. If c is None: Calculate angle between vectors a and b.

Parameters:

a (Vec3D) – First vector or point A
b (Vec3D) – Second vector or vertex point B
c (Vec3D, optional) – Optional third point C for angle ABC

Returns:

Angle in radians

Return type:

float

hbat.core.vector.dihedral_angle(a: Vec3D, b: Vec3D, c: Vec3D, d: Vec3D) → float[source]

Calculate dihedral angle between planes ABC and BCD.

Parameters:

a (Vec3D) – First point defining plane ABC
b (Vec3D) – Second point defining both planes
c (Vec3D) – Third point defining both planes
d (Vec3D) – Fourth point defining plane BCD

Returns:

Dihedral angle in radians

Return type:

float