`deeporigin.drug_discovery.LigandSet`¶

A class representing a set of Ligand objects.

Attributes:

Name	Type	Description
`ligands`	`list[Ligand]`	A list of Ligand instances contained in the set.

Attributes¶

ligands `class-attribute` `instance-attribute` ¶

ligands: list[Ligand] = field(default_factory=list)

Methods:¶

add_hydrogens ¶

add_hydrogens() -> None

Add hydrogens to all ligands in the set.

batches ¶

batches(batch_size: int | None) -> list[list[Ligand]]

Split this set into consecutive chunks of ligands (same order as :attr:ligands).

Parameters:

Name	Type	Description	Default
`batch_size`	`int \| None`	Maximum ligands per chunk. `None` returns a single chunk containing all ligands (including when the set is empty). Must be an `int` when not `None`; other types are rejected by runtime type checking. When the number of ligands is not a multiple of `batch_size`, the last batch is shorter (it holds the remainder only).	required

Returns:

Type	Description
`list[list[Ligand]]`	Non-empty list of batches when `batch_size` is `None`; otherwise a list
`list[list[Ligand]]`	of one or more consecutive slices of :attr:`ligands`.

Raises:

Type	Description
`ValueError`	If `batch_size` is set and not positive.
`BeartypeCallHintParamViolation`	If `batch_size` is neither `None` nor an `int` (e.g. a `float` or `str`).

compute_constraints ¶

compute_constraints(
    *, reference: Ligand, mcs_mol=None
) -> list[list[dict]]

Align a set of ligands to a reference ligand

download ¶

download(
    *,
    client: Optional[DeepOriginClient] = None,
    lazy: bool = True,
    max_workers: int = 20,
    skip_errors: bool = False,
    sanitize: bool = True,
    remove_hydrogens: bool = False
) -> None

Download platform files for ligands that have remote_path but no local file.

Selects ligands where :attr:~Ligand.remote_path is set and :attr:~Ligand.local_path is None, fetches distinct remotes in parallel with :meth:deeporigin.platform.files.FilesClient.download_many, assigns each ligand's :attr:~Ligand.local_path from the returned remote→local mapping, then reloads :attr:~Ligand.mol from SDF when applicable.

Ligands without remote_path, with empty remote_path, or that already have local_path set are left unchanged.

Parameters:

Name	Type	Description	Default
`client`	`Optional[DeepOriginClient]`	DeepOrigin client. If `None`, uses `DeepOriginClient()`.	`None`
`lazy`	`bool`	Passed to `download_many`; when `True`, existing cache files are reused.	`True`
`max_workers`	`int`	Maximum concurrent downloads for `download_many`.	`20`
`skip_errors`	`bool`	When `False` (default), any failed download in the batch raises. When `True`, per-ligand failures during path assignment or SDF reload are skipped and that ligand keeps prior state.	`False`
`sanitize`	`bool`	Passed to :meth:`Ligand.from_sdf` when rehydrating SDF downloads.	`True`
`remove_hydrogens`	`bool`	Passed to :meth:`Ligand.from_sdf` when rehydrating.	`False`

Raises:

Type	Description
`RuntimeError`	If `skip_errors` is `False` and `download_many` reports failures.

embed ¶

embed()

Minimize all ligands in the set using their 3D optimization routines. This calls the embed() method on each Ligand in the set.

filter_unsupported ¶

filter_unsupported() -> Self

Return a new set excluding ligands whose molecules contain atom types outside :data:~deeporigin.drug_discovery.constants.SUPPORTED_ATOM_SYMBOLS (see :meth:Ligand.has_unsupported_atoms).

from_csv `classmethod` ¶

from_csv(
    file_path: str | Path, smiles_column: str = "smiles"
) -> Self

Create a LigandSet instance from a CSV file containing SMILES strings and additional properties.

Parameters:

Name	Type	Description	Default
`file_path`	`str`	The path to the CSV file.	required
`smiles_column`	`str`	The name of the column containing SMILES strings. Defaults to "smiles".	`'smiles'`

Returns:

Name	Type	Description
`LigandSet`	`Self`	A LigandSet instance containing Ligand objects created from the CSV file.

Raises:

Type	Description
`FileNotFoundError`	If the file does not exist.
`DeepOriginException`	If the CSV does not contain the specified smiles column or if SMILES strings are invalid.

from_dir `classmethod` ¶

from_dir(directory: str | Path) -> Self

Create a LigandSet instance from a directory containing SDF files.

from_file `classmethod` ¶

from_file(
    file_path: str | Path,
    *,
    sanitize: bool = True,
    remove_hydrogens: bool = False,
    smiles_column: str = "smiles"
) -> Self

Create a LigandSet from an SDF or CSV file.

.sdf paths are validated as SDF (extension and content) and loaded with :meth:from_sdf. .csv paths are validated as CSV (extension) and loaded with :meth:from_csv.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| Path`	Path to an `.sdf` or `.csv` file.	required
`sanitize`	`bool`	Whether to sanitize molecules (SDF only). Defaults to True.	`True`
`remove_hydrogens`	`bool`	Whether to remove hydrogens (SDF only). Defaults to False.	`False`
`smiles_column`	`str`	Name of the SMILES column (CSV only). Defaults to `"smiles"`.	`'smiles'`

Returns:

Name	Type	Description
`LigandSet`	`Self`	Ligands created from the file.

Raises:

Type	Description
`FileNotFoundError`	If the file does not exist.
`DeepOriginException`	If the path is not a supported file type or loading fails.

from_ids `classmethod` ¶

from_ids(
    ids: list[str],
    *,
    client: DeepOriginClient | None = None,
    download: bool = True,
    ligand_inputs: list[dict[str, Any]] | None = None
) -> Self

Create a LigandSet by fetching ligands from the platform by ID.

Parameters:

Name	Type	Description	Default
`ids`	`list[str]`	List of Deep Origin Data Platform ligand IDs.	required
`client`	`DeepOriginClient \| None`	Optional API client. Uses the default if not provided.	`None`
`download`	`bool`	If True (default), download mol files when present. If False, hydrate from SMILES and set `remote_path` from the record (or `mol_file` on the matching `ligand_inputs` row) without downloading.	`True`
`ligand_inputs`	`list[dict[str, Any]] \| None`	Optional list of dicts (e.g. execution `userInputs.ligands`) keyed by `id`; `mol_file` on a row overrides the API path when `download` is False.	`None`

Returns:

Type	Description
`Self`	A new LigandSet containing the rehydrated ligands.

Notes

This delegates entity retrieval to client.entities.get_ligands() and preserves the order of the requested IDs.

from_rdkit_mols `classmethod` ¶

from_rdkit_mols(mols: list[Mol])

Create a LigandSet from a list of RDKit molecules.

from_sdf `classmethod` ¶

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

Create a LigandSet instance from an SDF file containing one or more molecules.

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
`LigandSet`	`Self`	A LigandSet instance containing Ligand objects created from the SDF file.

Raises:

Type	Description
`FileNotFoundError`	If the file does not exist.
`DeepOriginException`	If the file cannot be parsed correctly.

from_sdf_files `classmethod` ¶

from_sdf_files(
    file_paths: list[str],
    *,
    sanitize: bool = True,
    remove_hydrogens: bool = False
) -> Self

Create a LigandSet instance from multiple SDF files by concatenating them together.

Parameters:

Name	Type	Description	Default
`file_paths`	`list[str]`	A list of paths to SDF files.	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
`LigandSet`	`Self`	A LigandSet instance containing Ligand objects from all SDF files.

Raises:

Type	Description
`FileNotFoundError`	If any of the files do not exist.
`DeepOriginException`	If any of the files cannot be parsed correctly.

from_smiles `classmethod` ¶

from_smiles(smiles: list[str] | set[str]) -> Self

Create a LigandSet from a list of SMILES strings.

Parameters:

Name	Type	Description	Default
`smiles`	`list[str] \| set[str]`	SMILES strings to convert into ligands.	required

Returns:

Type	Description
`Self`	A new LigandSet containing one Ligand per SMILES string.

mcs ¶

mcs() -> Mol

Generates the Most Common Substructure (MCS) for ligands in a LigandSet

Returns:

Type	Description
`Mol`	smartsString (str) : SMARTS string representing the MCS

plot ¶

plot(
    *,
    x_label: str = "Pose Score",
    y_label: str = "Binding Energy (kcal/mol)",
    x: str = "POSE SCORE",
    y: str = "Binding Energy",
    output_file: Optional[str] = None,
    y_lim_max: Optional[float] = 0,
    width: int = 800,
    height: int = 800
)

Create a scatter plot of ligands using specified attributes for the axes.

The plot displays molecule images on hover and can be displayed inline or saved to an HTML file.

Parameters:

Name	Type	Description	Default
`x_label`	`str`	Label for the x-axis. Defaults to "Pose Score".	`'Pose Score'`
`y_label`	`str`	Label for the y-axis. Defaults to "Binding Energy (kcal/mol)".	`'Binding Energy (kcal/mol)'`
`x`	`str`	The name of the ligand property to use for the x-axis. Defaults to "POSE SCORE".	`'POSE SCORE'`
`y`	`str`	The name of the ligand property to use for the y-axis. Defaults to "Binding Energy".	`'Binding Energy'`
`output_file`	`Optional[str]`	Optional file path to save the HTML figure. If provided, the plot is saved to this file instead of being displayed. Defaults to None.	`None`

Raises:

Type	Description
`ValueError`	If the specified x or y properties are not found in the ligand data.

prepare ¶

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

Prepare all ligands in the set for downstream workflows.

This calls the prepare() method on each Ligand in the set, which performs: - Organic-parent selection (counterion stripping when unambiguous) - Kekulization - Fragment validation (rejects multiple non-identical fragments) - 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
`LigandSet`	`Self`	The prepared LigandSet (self), for chaining.

Raises:

Type	Description
`DeepOriginException`	If preparation fails for any ligand, unsupported atom types are present, or multiple non-identical fragments are detected.

random_sample ¶

random_sample(n: int) -> Self

Return a new LigandSet containing n randomly selected ligands.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of ligands to randomly sample	required

Returns:

Name	Type	Description
`LigandSet`	`Self`	A new LigandSet with n randomly selected ligands

Raises:

Type	Description
`ValueError`	If n is greater than the total number of ligands

remove_unsupported ¶

remove_unsupported() -> Self

Remove ligands with unsupported atom types from this set in place.

Drops ligands whose molecules contain atom types outside :data:~deeporigin.drug_discovery.constants.SUPPORTED_ATOM_SYMBOLS (see :meth:Ligand.has_unsupported_atoms). Prefer this before :meth:sync when a CSV or SDF includes metals or other atoms that docking workflows do not support.

Returns:

Name	Type	Description
`LigandSet`	`Self`	This set after unsupported ligands are removed, for chaining.

show ¶

show()

Visualize ligands in this LigandSet in 3D via the hosted molstarLib bundle.

Each ligand is loaded from its own SDF. When there are multiple ligands, the viewer shows one at a time; use the carousel (or arrow keys) to step through the set, or switch to "show all" to overlay them.

Returns:

Type	Description
	Result of :func:`~deeporigin.utils.notebook.render_html` for the Mol*
	viewer (`None` after Jupyter display, or a marimo `mo.Html` wrapper).

Raises:

Type	Description
`ValueError`	If the set has no ligands.
`DeepOriginException`	If visualization fails.

show_df ¶

show_df()

Show ligands in the set in a dataframe with 2D visualizations.

show_grid ¶

show_grid(
    mols_per_row: int = 3,
    sub_img_size: tuple[int, int] = (300, 300),
)

show all ligands in the LigandSet in a grid

sync ¶

sync(
    *,
    lazy: bool = False,
    client: Optional[DeepOriginClient] = None,
    remote_path: Optional[str] = None,
    show_progress: bool | None = None
) -> None

Sync all ligands in one import-dataset execution (SDF or SMILES CSV).

Structure-less ligands are written to a temporary CSV; structures use a multi-record SDF. Dedup and create/reuse run in the tool.

Requires client.project_id. Entity project_id values must match the client when set.

Large SMILES CSV batches use the import-dataset workflow (async start, poll until complete, then data-platform ingestion). Smaller CSV and all SDF batches use a single blocking served execution.

In Jupyter, a compact progress bar is shown by default. Pass show_progress=False to disable.

.. note::

This path will align with :meth:`~deeporigin.drug_discovery.structures.protein.Protein.sync`
(served import-dataset register flow). Large refactors here are deferred
until that migration lands; tool execution still requires a scoped client.

to_dataframe ¶

to_dataframe() -> DataFrame

Convert the LigandSet to a pandas DataFrame.

to_dict ¶

to_dict() -> list[dict[str, str]]

Convert this set to a list of dicts, one per ligand.

Each dict has id (platform id when set, else "0", "1", … by position in this set) and smiles. For batched API calls with globally unique ids, ensure each :class:Ligand id is set before building the set.

Returns:

Type	Description
`list[dict[str, str]]`	One `{"id": ..., "smiles": ...}` dict per ligand, in order.

Raises:

Type	Description
`ValueError`	If a ligand has no non-empty `smiles`.

to_rdkit_mols ¶

to_rdkit_mols() -> list[Mol]

Convert all ligands in the set to RDKit molecules.

to_sdf ¶

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

Write all ligands to one SDF file, preserving properties from each mol.

This is a local operation. Each ligand must already be rehydrated if it has remote_path but no local file (call :meth:Ligand.download or :meth:LigandSet.download first, or use from_id(..., download=True)).

Parameters:

Name	Type	Description	Default
`output_path`	`Optional[str]`	Path to the output SDF file.	`None`

Returns:

Type	Description
`str`	Path to the written SDF file.

to_smiles ¶

to_smiles() -> list[str]

Convert all ligands in the set to SMILES strings.

upload ¶

upload(
    *,
    client: Optional[DeepOriginClient] = None,
    max_workers: int = 20
) -> None

Upload structure files for ligands that have a local file.

For each ligand with non-None :attr:~Ligand.local_path, serializes and assigns :attr:~Ligand.remote_path (same contract as :meth:Ligand.upload), then uploads all files in parallel via :meth:deeporigin.platform.files.FilesClient.upload_many. Ligands without local_path are skipped.

Parameters:

Name	Type	Description	Default
`client`	`Optional[DeepOriginClient]`	DeepOrigin client. If None, uses `DeepOriginClient()`.	`None`
`max_workers`	`int`	Maximum concurrent uploads (passed to `upload_many`).	`20`

deeporigin.drug_discovery.LigandSet¶

Attributes¶

ligands class-attribute instance-attribute ¶

Methods:¶

add_hydrogens ¶

batches ¶

compute_constraints ¶

download ¶

embed ¶

filter_unsupported ¶

from_csv classmethod ¶

from_dir classmethod ¶

from_file classmethod ¶

from_ids classmethod ¶

from_rdkit_mols classmethod ¶

from_sdf classmethod ¶

from_sdf_files classmethod ¶

from_smiles classmethod ¶

mcs ¶

plot ¶

prepare ¶

random_sample ¶

remove_unsupported ¶

show ¶

show_df ¶

show_grid ¶

sync ¶

to_dataframe ¶

to_dict ¶

to_rdkit_mols ¶

to_sdf ¶

to_smiles ¶

upload ¶

`deeporigin.drug_discovery.LigandSet`¶

ligands `class-attribute` `instance-attribute` ¶

from_csv `classmethod` ¶

from_dir `classmethod` ¶

from_file `classmethod` ¶

from_ids `classmethod` ¶

from_rdkit_mols `classmethod` ¶

from_sdf `classmethod` ¶

from_sdf_files `classmethod` ¶

from_smiles `classmethod` ¶