deeporigin.drug_discovery.Ligand

Bases: Entity

A class representing a ligand molecule in drug discovery workflows.

The Ligand class provides functionality to create, manipulate, and analyze small molecules (ligands) in computational drug discovery. It supports various input formats and provides methods for property prediction, visualization, and file operations.

Attributes

atom_types property

atom_types

available_for_docking class-attribute instance-attribute

available_for_docking: bool = field(
    init=False, default=True
)

block_content class-attribute instance-attribute

block_content: str | None = None

block_type class-attribute instance-attribute

block_type: str | None = None

contains_boron property

contains_boron: bool

Check if the ligand contains boron atoms.

Currently, ligands with boron atoms are not supported for docking.

Returns:

Name	Type	Description
bool	bool	True if the ligand contains boron atoms, False otherwise.

coordinates property

coordinates

file_path class-attribute instance-attribute

file_path: str | None = None

identifier class-attribute instance-attribute

identifier: str | None = None

mol class-attribute instance-attribute

mol: Mol | None = None

name class-attribute instance-attribute

name: str | None = None

properties class-attribute instance-attribute

properties: dict = field(default_factory=dict)

save_to_file class-attribute instance-attribute

save_to_file: bool = False

seed class-attribute instance-attribute

seed: int | None = None

smiles class-attribute instance-attribute

smiles: str | None = None

xref_ins_code class-attribute instance-attribute

xref_ins_code: str | None = None

xref_protein class-attribute instance-attribute

xref_protein: str | None = None

xref_protein_chain_id class-attribute instance-attribute

xref_protein_chain_id: str | None = None

xref_residue_id class-attribute instance-attribute

xref_residue_id: str | None = None

Functions

add_hydrogens

add_hydrogens(add_coordinates: bool = True)

Add hydrogens to the molecule.

Parameters:

Name	Type	Description	Default
add_coordinates	bool	Whether to generate coordinates for added hydrogens	True

admet_properties

admet_properties(use_cache: bool = True) -> dict

Predict ADMET properties for the ligand using DO's molprops model.

draw

draw()

Draw the contained rdkit molecule using rdkit methods

embed

embed(add_hydrogens: bool = True, seed: int = -1)

Generate 3D coordinates for the molecule.

Parameters:

Name	Type	Description	Default
add_hydrogens	bool	Whether to add hydrogens	True
seed	int	Random seed for coordinate generation	-1

from_base64 classmethod

from_base64(
    base64_string: str,
    name: str = "",
    save_to_file: bool = False,
    **kwargs: Any
) -> Ligand

Create a Ligand instance from a base64 encoded SDF string.

Parameters:

Name	Type	Description	Default
base64_string	str	Base64 encoded SDF content	required
name	str	Name of the ligand. Defaults to "".	''
save_to_file	bool	Whether to save the ligand to file. Defaults to False.	False
**kwargs	Any	Additional arguments to pass to the constructor	{}

Returns:

Name	Type	Description
Ligand	Ligand	A new Ligand instance

Raises:

Type	Description
DeepOriginException	If the base64 string cannot be decoded or parsed

from_block_content classmethod

from_block_content(
    block_content: str,
    block_type: str,
    name: str = "",
    save_to_file: bool = False,
    **kwargs: Any
) -> Ligand

Create a Ligand instance from block content.

Parameters:

Name	Type	Description	Default
block_content	str	String containing the molecule data	required
block_type	str	Format of the block content ('mol', 'mol2', 'sdf', 'pdb')	required
name	str	Name of the ligand. Defaults to "".	''
save_to_file	bool	Whether to save the ligand to file. Defaults to False.	False
**kwargs	Any	Additional arguments to pass to the constructor	{}

Returns:

Name	Type	Description
Ligand	Ligand	A new Ligand instance

from_identifier classmethod

from_identifier(identifier: str)

Create a Ligand instance from a compound name.

Parameters:

Name	Type	Description	Default
identifier	str	The identifier to resolve to a SMILES string.	required

Raises:

Type	Description
DeepOriginException	If no compound is found for the given name
AssertionError	If neither smiles nor name is provided

from_rdkit_mol classmethod

from_rdkit_mol(
    mol: Mol,
    name: Optional[str] = None,
    save_to_file: bool = False,
    **kwargs: Any
)

Create a Ligand instance from an RDKit Mol object.

Parameters:

Name	Type	Description	Default
mol	Mol	RDKit molecule object to convert to a Ligand	required
name	str	Name of the ligand. Defaults to "".	None
save_to_file	bool	Whether to save the ligand to file. Defaults to False.	False
**kwargs	Any	Additional arguments to pass to the constructor	{}

from_sdf classmethod

from_sdf(
    file_path: str,
    *,
    sanitize: bool = True,
    remove_hydrogens: bool = False
) -> Ligand

Create a single Ligand instance from an SDF file containing exactly one molecule.

Parameters:

Name	Type	Description	Default
file_path	str	The path to the SDF file.	required
sanitize	bool	Whether to sanitize molecules. Defaults to True.	True
remove_hydrogens	bool	Whether to remove hydrogens. Defaults to False.	False

Returns:

Name	Type	Description
Ligand	Ligand	The Ligand instance created from the SDF file.

Raises:

Type	Description
FileNotFoundError	If the file does not exist.
DeepOriginException	If the file cannot be parsed correctly or contains more than one molecule.

from_smiles classmethod

from_smiles(
    smiles: str,
    name: str = "",
    save_to_file: bool = False,
    **kwargs: Any
) -> Ligand

Create a Ligand instance from a SMILES string.

Parameters:

Name	Type	Description	Default
smiles	str	SMILES string representing the ligand	required
name	str	Name of the ligand. Defaults to "".	''
save_to_file	bool	Whether to save the ligand to file. Defaults to False.	False
**kwargs	Any	Additional arguments to pass to the constructor	{}

Returns:

Name	Type	Description
Ligand	Ligand	A new Ligand instance

get_center

get_center() -> list[number]

Get the center of the ligand based on its coordinates.

Returns: - list: The center coordinates of the ligand. - None: If coordinates are not available.

get_conformer

get_conformer(conformer_id: int = 0)

Get a specific conformer of the molecule.

Parameters:

Name	Type	Description	Default
conformer_id	int	Conformer index	0

get_conformer_id

get_conformer_id() -> int

Get the ID of the current conformer.

Returns:

Name	Type	Description
int	int	Conformer ID

get_coordinates

get_coordinates(i: int = 0)

Get the coordinates of atoms in a specific conformer.

Parameters:

Name	Type	Description	Default
i	int	Conformer index	0

get_formula

get_formula() -> str

Get the chemical formula of the molecule.

get_heavy_atom_count

get_heavy_atom_count() -> int

Get the number of heavy atoms in the molecule.

get_property

get_property(prop_name: str)

Get the value of a property for the ligand molecule.

Parameters: - prop_name (str): Name of the property to retrieve.

Returns: - The value of the property if it exists, otherwise None.

get_species

get_species() -> list[str]

Get the atomic symbols of all atoms in the molecule.

Returns:

Name	Type	Description
list	list[str]	List of atomic symbols

mol_from_block classmethod

mol_from_block(
    block_type: str,
    block: str,
    sanitize: bool = True,
    remove_hs: bool = False,
) -> Mol

Create a molecule from a block of text.

Parameters:

Name	Type	Description	Default
block_type	str	Type of the input block	required
block	str	Text block containing molecular data	required
sanitize	bool	Whether to sanitize the molecule	True
remove_hs	bool	Whether to remove hydrogens	False

Returns:

Type	Description
Mol	Chem.Mol: RDKit molecule object

mol_from_file classmethod

mol_from_file(
    *,
    file_type: FILE_FORMATS,
    file_path: str,
    sanitize: bool = True,
    remove_hs: bool = False
) -> Mol

Create a molecule from a file.

Parameters:

Name	Type	Description	Default
file_type	str	Type of the input file (must be in FILE_FORMATS)	required
file_path	str	Path to the input file	required
sanitize	bool	Whether to sanitize the molecule	True
remove_hs	bool	Whether to remove hydrogens	False

Returns:

Type	Description
Mol	Chem.Mol: RDKit molecule object

Raises:

Type	Description
DeepOriginException	If the file format is invalid or parsing fails
NotImplementedError	If the file type is not supported

process_mol

process_mol() -> None

Clean the ligand molecule by removing hydrogens and sanitizing the structure.

Raises:

Type	Description
DeepOriginException	If salt removal or kekulization fails

protonate

protonate(
    *, ph: number = 7.4, filter_percentage: number = 1.0
)

Protonate the ligand at a given pH.

Only the most abundant species is retained.

set_conformer_id

set_conformer_id(i=0)

Set the ID of the current conformer.

Parameters:

Name	Type	Description	Default
i	int	New conformer ID	0

set_property

set_property(prop_name: str, prop_value)

Set a property for the ligand molecule.

Parameters: - prop_name (str): Name of the property. - prop_value: Value of the property.

show

show() -> str

Visualize the current state of the ligand molecule.

Returns: - str: HTML representation of the visualization.

Raises: - Exception: If visualization fails.

to_base64

to_base64() -> str

Convert the ligand to base64 encoded SDF format.

Returns:

Name	Type	Description
str	str	Base64 encoded string of the SDF file content

to_hash

to_hash() -> str

Convert the ligand to SHA256 hash of the SDF file content.

Returns:

Name	Type	Description
str	str	SHA256 hash string of the SDF file content

to_mol

to_mol(output_path: Optional[str] = None) -> str | Path

Write the ligand to a MOL file.

to_molblock

to_molblock() -> str

Generate a MOL block representation of the molecule.

Returns:

Name	Type	Description
str	str	MOL block string

to_pdb

to_pdb(output_path: Optional[str] = None) -> str | Path

Write the ligand to a PDB file.

to_sdf

to_sdf(output_path: Optional[str] = None) -> str

Write the ligand to an SDF file.

update_coordinates

update_coordinates(coordinates: ndarray)

update coordinates of the ligand structure

upload

upload()

Upload the entity to the remote server.

write_to_file

write_to_file(
    output_path: Optional[str] = None,
    output_format: Literal["mol", "sdf", "pdb"] = "sdf",
) -> str | Path

Writes the ligand molecule to a file, including all properties.

Parameters: - output_path (str): Path where the ligand will be written. - output_format (Literal[".mol", ".sdf", ".pdb", "mol", "sdf", "pdb"]): Format to write the ligand in.

Raises:

Type	Description
-DeepOriginException	If the file extension is unsupported.
-Exception	If writing to the file fails.