Core Data Structures

Molecular structure classes for HBAT.

This module contains the core data structures representing molecular entities including atoms, bonds, and residues from PDB files.

class hbat.core.structure.Bond(atom1_serial: int, atom2_serial: int, bond_type: str = 'covalent', distance: float | None = None, detection_method: str = 'distance_based')

Bases: object

Represents a chemical bond between two atoms.

This class stores information about atomic bonds, including the atoms involved and bond type/origin.

Parameters:

• atom1_serial (int) – Serial number of first atom

• atom2_serial (int) – Serial number of second atom

• bond_type (str) – Type of bond (‘covalent’, ‘explicit’, etc.)

• distance (Optional[float]) – Distance between bonded atoms in Angstroms

• detection_method (str) – Method used to detect this bond

__init__(atom1_serial: int, atom2_serial: int, bond_type: str = 'covalent', distance: float | None = None, detection_method: str = 'distance_based') → None

Initialize a Bond object.

Parameters:

• atom1_serial (int) – Serial number of first atom

• atom2_serial (int) – Serial number of second atom

• bond_type (str) – Type of bond (‘covalent’, ‘explicit’, etc.)

• distance (Optional[float]) – Distance between bonded atoms in Angstroms

• detection_method (str) – Method used to detect this bond

involves_atom(serial: int) → bool

Check if bond involves the specified atom.

Parameters:

serial (int) – Atom serial number

Returns:

True if bond involves this atom

Return type:

bool

get_partner(serial: int) → int | None

Get the bonding partner of the specified atom.

Parameters:

serial (int) – Atom serial number

Returns:

Serial number of bonding partner, None if atom not in bond

Return type:

Optional[int]

__iter__() → Iterator[Tuple[str, Any]]

Iterate over bond attributes as (name, value) pairs.

Returns:

Iterator of (attribute_name, value) tuples

Return type:

Iterator[Tuple[str, Any]]

to_dict() → Dict[str, Any]

Convert bond to dictionary.

Returns:

Dictionary representation of the bond

Return type:

Dict[str, Any]

classmethod fields() → List[str]

Get list of field names.

Returns:

List of field names

Return type:

List[str]

__repr__() → str

String representation of the bond.

__eq__(other: object) → bool

Check equality with another Bond.

__hash__() → int

Hash function for Bond objects to make them hashable.

class hbat.core.structure.Atom(serial: int, name: str, alt_loc: str, res_name: str, chain_id: str, res_seq: int, i_code: str, coords: NPVec3D, occupancy: float, temp_factor: float, element: str, charge: str, record_type: str, residue_type: str = 'L', backbone_sidechain: str = 'S', aromatic: str = 'N')

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 (NPVec3D) – 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)

• residue_type (str) – Residue type classification (P=Protein, D=DNA, R=RNA, L=Ligand)

• backbone_sidechain (str) – Backbone/sidechain classification (B=Backbone, S=Sidechain)

• aromatic (str) – Aromatic classification (A=Aromatic, N=Non-aromatic)

__init__(serial: int, name: str, alt_loc: str, res_name: str, chain_id: str, res_seq: int, i_code: str, coords: NPVec3D, occupancy: float, temp_factor: float, element: str, charge: str, record_type: str, residue_type: str = 'L', backbone_sidechain: str = 'S', aromatic: str = 'N') → None

Initialize an Atom object.

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 (NPVec3D) – 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)

• residue_type (str) – Residue type classification (P=Protein, D=DNA, R=RNA, L=Ligand)

• backbone_sidechain (str) – Backbone/sidechain classification (B=Backbone, S=Sidechain)

• aromatic (str) – Aromatic classification (A=Aromatic, N=Non-aromatic)

is_hydrogen() → bool

Check if atom is hydrogen.

Returns:

True if atom is hydrogen or deuterium

Return type:

bool

is_metal() → bool

Check if atom is a metal.

Returns:

True if atom is a common metal ion

Return type:

bool

__iter__() → Iterator[Tuple[str, Any]]

Iterate over atom attributes as (name, value) pairs.

Returns:

Iterator of (attribute_name, value) tuples

Return type:

Iterator[Tuple[str, Any]]

to_dict() → Dict[str, Any]

Convert atom to dictionary.

Returns:

Dictionary representation of the atom

Return type:

Dict[str, Any]

classmethod fields() → List[str]

Get list of field names.

Returns:

List of field names

Return type:

List[str]

__repr__() → str

String representation of the atom.

__eq__(other: object) → bool

Check equality with another Atom.

__hash__() → int

Hash function for Atom objects to make them hashable.

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

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

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

Initialize a Residue object.

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

get_atom(atom_name: str) → Atom | None

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]

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() → NPVec3D

Calculate center of mass of residue.

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

Returns:

Center of mass coordinates

Return type:

NPVec3D

get_aromatic_center() → NPVec3D | None

Calculate aromatic ring center if residue is aromatic.

For aromatic residues (PHE, TYR, TRP, HIS), calculates the geometric center of the aromatic ring atoms.

Returns:

Center coordinates of aromatic ring, None if not aromatic

Return type:

Optional[NPVec3D]

__iter__() → Iterator[Tuple[str, Any]]

Iterate over residue attributes as (name, value) pairs.

Returns:

Iterator of (attribute_name, value) tuples

Return type:

Iterator[Tuple[str, Any]]

to_dict() → Dict[str, Any]

Convert residue to dictionary.

Returns:

Dictionary representation of the residue

Return type:

Dict[str, Any]

classmethod fields() → List[str]

Get list of field names.

Returns:

List of field names

Return type:

List[str]

__repr__() → str

String representation of the residue.

__eq__(other: object) → bool

Check equality with another Residue.

__hash__() → int

Hash function for Residue objects to make them hashable.