PDB Structure Fixer

PDB Structure Fixer#

PDB structure fixing module for adding missing hydrogen atoms.

This module provides functionality to add missing hydrogen atoms to PDB structures using either OpenBabel or PDBFixer tools. It integrates with HBAT’s internal data structures and provides a clean interface for structure enhancement.

exception hbat.core.pdb_fixer.PDBFixerError[source]#

Bases: Exception

Exception raised when PDB fixing operations fail.

class hbat.core.pdb_fixer.PDBFixer[source]#

Bases: object

Fix PDB structures by adding missing hydrogen atoms.

This class provides methods to add missing hydrogen atoms to protein structures using either OpenBabel or PDBFixer with OpenMM. It works with HBAT’s internal atom and residue data structures.

__init__() → None[source]#

Initialize PDB fixer.

add_missing_hydrogens(atoms: List[Atom], method: str = 'openbabel', pH: float = 7.0, **kwargs: Any) → List[Atom][source]#

Add missing hydrogen atoms to a list of atoms.

Takes a list of HBAT Atom objects and returns a new list with missing hydrogen atoms added using the specified method.

Parameters:

  • atoms (List[Atom]) – List of atoms to process

  • method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)

  • pH (float) – pH value for protonation (pdbfixer only)

  • kwargs (Any) – Additional parameters for the fixing method

Returns:

List of atoms with hydrogens added

Return type:

List[Atom]

Raises:

PDBFixerError if fixing fails

add_missing_heavy_atoms(atoms: List[Atom], method: str = 'pdbfixer', **kwargs: Any) → List[Atom][source]#

Add missing heavy atoms to a structure.

Uses PDBFixer to identify and add missing heavy atoms in residues. This is particularly useful for structures with incomplete side chains.

Parameters:

  • atoms (List[Atom]) – List of atoms to process

  • method (str) – Method to use (only ‘pdbfixer’ supports this)

  • kwargs (Any) – Additional parameters

Returns:

List of atoms with missing heavy atoms added

Return type:

List[Atom]

Raises:

PDBFixerError if fixing fails

convert_nonstandard_residues(atoms: List[Atom], custom_replacements: Dict[str, str] | None = None) → List[Atom][source]#

Convert non-standard residues to their standard equivalents using PDBFixer.

This method uses PDBFixer’s built-in findNonstandardResidues() and replaceNonstandardResidues() methods to properly handle non-standard residues.

Parameters:

  • atoms (List[Atom]) – List of atoms to process

  • custom_replacements (Optional[Dict[str, str]]) – Custom residue replacements to apply

Returns:

List of atoms with converted residue names

Return type:

List[Atom]

remove_heterogens(atoms: List[Atom], keep_water: bool = True) → List[Atom][source]#

Remove unwanted heterogens from the structure using PDBFixer.

Uses PDBFixer’s built-in removeHeterogens() method to properly handle heterogen removal with the option to keep water molecules.

Parameters:

  • atoms (List[Atom]) – List of atoms to process

  • keep_water (bool) – Whether to keep water molecules

Returns:

List of atoms with heterogens removed

Return type:

List[Atom]

fix_structure_file(input_path: str, output_path: str | None = None, method: str = 'openbabel', pH: float = 7.0, overwrite: bool = False, **kwargs: Any) → str[source]#

Fix a PDB file by adding missing hydrogen atoms.

Parameters:

  • input_path (str) – Path to input PDB file

  • output_path (Optional[str]) – Path for output file (optional)

  • method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)

  • pH (float) – pH value for protonation (pdbfixer only)

  • overwrite (bool) – Whether to overwrite existing output file

  • kwargs (Any) – Additional parameters for the fixing method

Returns:

Path to the output file

Return type:

str

Raises:

PDBFixerError if fixing fails

fix_pdb_file_to_file(input_pdb_path: str, output_pdb_path: str, method: str = 'openbabel', add_hydrogens: bool = True, add_heavy_atoms: bool = False, convert_nonstandard: bool = False, remove_heterogens: bool = False, keep_water: bool = True, pH: float = 7.0, **kwargs: Any) → bool[source]#

Fix a PDB file and save the result to another file.

This method processes the original PDB file directly and saves the fixed structure to a new file, preserving proper PDB formatting.

Parameters:

  • input_pdb_path (str) – Path to the original PDB file

  • output_pdb_path (str) – Path where the fixed PDB should be saved

  • method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)

  • add_hydrogens (bool) – Whether to add missing hydrogen atoms

  • add_heavy_atoms (bool) – Whether to add missing heavy atoms (pdbfixer only)

  • convert_nonstandard (bool) – Whether to convert nonstandard residues (pdbfixer only)

  • remove_heterogens (bool) – Whether to remove heterogens (pdbfixer only)

  • keep_water (bool) – Whether to keep water molecules when removing heterogens

  • pH (float) – pH value for protonation (pdbfixer only)

  • kwargs (Any) – Additional parameters

Returns:

True if fixing succeeded, False otherwise

Return type:

bool

Raises:

PDBFixerError if fixing fails

get_missing_hydrogen_info(atoms: List[Atom]) → Dict[str, Any][source]#

Analyze structure for missing hydrogen information.

Parameters:

atoms (List[Atom]) – List of atoms to analyze

Returns:

Dictionary with hydrogen analysis information

Return type:

Dict[str, Any]

hbat.core.pdb_fixer.add_missing_hydrogens(atoms: List[Atom], method: str = 'openbabel', pH: float = 7.0, **kwargs: Any) → List[Atom][source]#

Convenience function to add missing hydrogen atoms.

Parameters:

  • atoms (List[Atom]) – List of atoms to process

  • method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)

  • pH (float) – pH value for protonation (pdbfixer only)

  • kwargs (Any) – Additional parameters for the fixing method

Returns:

List of atoms with hydrogens added

Return type:

List[Atom]

hbat.core.pdb_fixer.fix_pdb_file(input_path: str, output_path: str | None = None, method: str = 'openbabel', pH: float = 7.0, overwrite: bool = False, **kwargs: Any) → str[source]#

Convenience function to fix a PDB file.

Parameters:

  • input_path (str) – Path to input PDB file

  • output_path (Optional[str]) – Path for output file (optional)

  • method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)

  • pH (float) – pH value for protonation (pdbfixer only)

  • overwrite (bool) – Whether to overwrite existing output file

  • kwargs (Any) – Additional parameters for the fixing method

Returns:

Path to the output file

Return type:

str

hbat.core.pdb_fixer.add_missing_heavy_atoms(atoms: List[Atom], method: str = 'pdbfixer', **kwargs: Any) → List[Atom][source]#

Convenience function to add missing heavy atoms.

Parameters:

  • atoms (List[Atom]) – List of atoms to process

  • method (str) – Method to use (only ‘pdbfixer’ supports this)

  • kwargs (Any) – Additional parameters

Returns:

List of atoms with missing heavy atoms added

Return type:

List[Atom]

hbat.core.pdb_fixer.convert_nonstandard_residues(atoms: List[Atom], custom_replacements: Dict[str, str] | None = None) → List[Atom][source]#

Convenience function to convert non-standard residues using PDBFixer.

Uses PDBFixer’s built-in findNonstandardResidues() and replaceNonstandardResidues() methods to properly handle non-standard residue conversion.

Parameters:

  • atoms (List[Atom]) – List of atoms to process

  • custom_replacements (Optional[Dict[str, str]]) – Custom residue replacements to apply

Returns:

List of atoms with converted residue names

Return type:

List[Atom]

hbat.core.pdb_fixer.remove_heterogens(atoms: List[Atom], keep_water: bool = True) → List[Atom][source]#

Convenience function to remove unwanted heterogens using PDBFixer.

Uses PDBFixer’s built-in removeHeterogens() method which only supports the option to keep or remove water molecules.

Parameters:

  • atoms (List[Atom]) – List of atoms to process

  • keep_water (bool) – Whether to keep water molecules

Returns:

List of atoms with heterogens removed

Return type:

List[Atom]

Contents