`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,
    client: Optional[DeepOriginClient] = None
) -> 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
) -> Self

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`	`Self`	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
) -> Self

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`	`Self`	A new Ligand instance

from_identifier `classmethod` ¶

from_identifier(identifier: str) -> Self

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
) -> Self

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 | Path,
    *,
    sanitize: bool = True,
    remove_hydrogens: bool = False
) -> Self

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`	`Self`	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
) -> Self

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`	`Self`	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

has_hydrogens ¶

has_hydrogens() -> bool

Check if the molecule contains hydrogen atoms.

This method determines if hydrogens are present by comparing the canonical SMILES string of the molecule with and without explicit hydrogens added. If the SMILES strings differ, the molecule contains hydrogens.

Returns:

Name	Type	Description
`bool`	`bool`	True if the molecule contains hydrogen atoms, False otherwise

is_charged ¶

is_charged() -> bool

Check if the molecule is charged.

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

prepare ¶

prepare(*, remove_hydrogens: bool = False) -> Self

Prepare the ligand for downstream workflows.

The routine performs the following using RDKit and internal utilities: - Salt removal - Kekulization - Validation of atom types against supported symbols

Parameters:

Name	Type	Description	Default
`remove_hydrogens`	`bool`	Whether to remove hydrogens from the SMILES representation. Defaults to False (preserve hydrogens).	`False`

Returns:

Name	Type	Description
`Ligand`	`Self`	The prepared ligand (self), for chaining.

Raises:

Type	Description
`DeepOriginException`	If preparation fails or unsupported atom types are present.

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,
    client: Optional[DeepOriginClient] = None,
    use_cache: bool = True,
    quote: bool = False
)

Protonate the ligand at a given pH using the DeepOrigin API.

This method calculates the protonation states of the ligand molecule at the specified pH value and updates the ligand's molecule and SMILES representation with the most abundant protonation state. The protonation state affects the charge distribution of ionizable groups (e.g., carboxylic acids, amines) in the molecule, which is important for accurate molecular modeling and docking simulations.

The method modifies the ligand in place by updating both self.mol and self.smiles with the protonated form of the molecule.

Parameters:

Name	Type	Description	Default
`ph`	`number`	pH value at which to protonate the ligand. Defaults to 7.4 (physiological pH).	`7.4`
`filter_percentage`	`number`	Percentage threshold for filtering protonation states. Only species with abundance above this threshold are considered. Defaults to 1.0 (100%), meaning only the most abundant species is retained.	`1.0`
`client`	`Optional[DeepOriginClient]`	DeepOrigin client instance to use for API calls. If None, a default client is obtained using `DeepOriginClient.get()`. Defaults to None.	`None`
`use_cache`	`bool`	Whether to use cached protonation results if available. Caching is based on the SMILES string and pH value. Defaults to True.	`True`
`quote`	`bool`	If True, request a quote for the protonation operation instead of executing it. Defaults to False.	`False`

Note

The protonation process may change the SMILES string of the ligand if ionizable groups are present and their protonation state changes at the specified pH.

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 | None

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(client: DeepOriginClient | None = None)

Upload the entity to the remote server.

Overwrites the existing file if it exists.

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.

Preparation¶

Use Ligand.prepare() to perform common preparation steps before docking:

salt removal, kekulization
validation of atom symbols against supported types

Example:

from deeporigin.drug_discovery.structures import Ligand

lig = Ligand.from_smiles("CCO", name="Ethanol")
lig.prepare()  # Preserves hydrogens by default
lig.prepare(remove_hydrogens=True)  # Remove hydrogens from SMILES

deeporigin.drug_discovery.Ligand¶

Attributes¶

atom_types property ¶

available_for_docking class-attribute instance-attribute ¶

block_content class-attribute instance-attribute ¶

block_type class-attribute instance-attribute ¶

contains_boron property ¶

coordinates property ¶

file_path class-attribute instance-attribute ¶

identifier class-attribute instance-attribute ¶

mol class-attribute instance-attribute ¶

name class-attribute instance-attribute ¶

properties class-attribute instance-attribute ¶

save_to_file class-attribute instance-attribute ¶

seed class-attribute instance-attribute ¶

smiles class-attribute instance-attribute ¶

xref_ins_code class-attribute instance-attribute ¶

xref_protein class-attribute instance-attribute ¶

xref_protein_chain_id class-attribute instance-attribute ¶

xref_residue_id class-attribute instance-attribute ¶

Functions¶

add_hydrogens ¶

admet_properties ¶

draw ¶

embed ¶

from_base64 classmethod ¶

from_block_content classmethod ¶

from_identifier classmethod ¶

from_rdkit_mol classmethod ¶

from_sdf classmethod ¶

from_smiles classmethod ¶

get_center ¶

get_conformer ¶

get_conformer_id ¶

get_coordinates ¶

get_formula ¶

get_heavy_atom_count ¶

get_property ¶

get_species ¶

has_hydrogens ¶

is_charged ¶

mol_from_block classmethod ¶

mol_from_file classmethod ¶

prepare ¶

process_mol ¶

protonate ¶

set_conformer_id ¶

set_property ¶

show ¶

to_base64 ¶

to_hash ¶

to_mol ¶

to_molblock ¶

to_pdb ¶

to_sdf ¶

update_coordinates ¶

upload ¶

write_to_file ¶

Preparation¶

`deeporigin.drug_discovery.Ligand`¶

atom_types `property` ¶

available_for_docking `class-attribute` `instance-attribute` ¶

block_content `class-attribute` `instance-attribute` ¶

block_type `class-attribute` `instance-attribute` ¶

contains_boron `property` ¶

coordinates `property` ¶

file_path `class-attribute` `instance-attribute` ¶

identifier `class-attribute` `instance-attribute` ¶

mol `class-attribute` `instance-attribute` ¶

name `class-attribute` `instance-attribute` ¶

properties `class-attribute` `instance-attribute` ¶

save_to_file `class-attribute` `instance-attribute` ¶

seed `class-attribute` `instance-attribute` ¶

smiles `class-attribute` `instance-attribute` ¶

xref_ins_code `class-attribute` `instance-attribute` ¶

xref_protein `class-attribute` `instance-attribute` ¶

xref_protein_chain_id `class-attribute` `instance-attribute` ¶

xref_residue_id `class-attribute` `instance-attribute` ¶

from_base64 `classmethod` ¶

from_block_content `classmethod` ¶

from_identifier `classmethod` ¶

from_rdkit_mol `classmethod` ¶

from_sdf `classmethod` ¶

from_smiles `classmethod` ¶

mol_from_block `classmethod` ¶

mol_from_file `classmethod` ¶