Skip to content

deeporigin.drug_discovery.metabolism

Metabolism drives platform tool deeporigin.metabolism. It scores ligands for sites of metabolism on cytochrome P450 (CYP) isoforms.

Use run() for small batches (fewer than 30 ligands); it blocks and returns a table of sites (every enzyme the tool scored). For 30 or more ligands, call start(), then wait() or watch(), then get_results(). get_molecules() returns molecule-level reliability tiers. There is no cost quote and no client-side ligand cap.

Metabolism -- predict sites of metabolism for ligands.

Backed by the platform tool deeporigin.metabolism. One :class:Metabolism instance is configured with ligands, then executed with a blocking :meth:run (small batches) or asynchronous :meth:start (larger batches). :meth:run returns a :class:pandas.DataFrame of Metabolism site rows (atom, enzyme, site confidence). :meth:get_molecules returns molecule-level confidence_tier rows.

The tool scores every cytochrome P450 isoform it supports; the client does not select or filter enzymes. tool_version stays "latest". Ligands are not mutated. Payload id is sent only when :attr:~deeporigin.drug_discovery.structures.ligand.Ligand.id is already set.

Sync usage (blocking; fewer than 30 ligands)::

from deeporigin.drug_discovery import Metabolism, Ligand

job = Metabolism(ligands=Ligand.from_smiles("CCO"))
sites = job.run()
mols = job.get_molecules()

Async usage (30 or more ligands, or any size)::

job = Metabolism(ligands=ligands)
job.start()
await job.watch()  # or job.wait()
sites = job.get_results()

Classes

Metabolism

Bases: Execution, SyncExecutableMixin, AsyncExecutableMixin, NotebookWatchMixin

Predict sites of metabolism for ligands via deeporigin.metabolism.

The tool scores every cytochrome P450 isoform it supports. Ligands are not mutated (contrast with :class:~deeporigin.drug_discovery.molprops.Molprops).

Use :meth:run for fewer than :data:~deeporigin.utils.constants.METABOLISM_WORKFLOW_LIGAND_THRESHOLD ligands (blocking). For larger batches, call :meth:start, then :meth:wait or :meth:watch, then :meth:get_results.

Attributes:

Name Type Description
ligands list[Ligand]

Ligands whose SMILES are sent to the tool.
name

Execution label, set from the ligand count unless overridden.

Attributes

ligands property 
ligands: list[Ligand]

Ligands targeted by this run (read-only).

name instance-attribute 
name = (
    name
    if name is not None
    else _metabolism_default_name(len(self._ligands))
)
tool_key class-attribute instance-attribute 
tool_key: str = TOOL_KEYS_AND_VERSIONS["metabolism"][
    "tool_key"
]
tool_version class-attribute instance-attribute 
tool_version: str = TOOL_KEYS_AND_VERSIONS["metabolism"][
    "tool_version"
]

Methods:

from_dto classmethod 
from_dto(
    dto: dict[str, Any],
    *,
    client: DeepOriginClient | None = None
) -> Self

Construct a Metabolism from a tools execution DTO.

Restores ligands from userInputs (falling back to inputs).

Parameters:

Name Type Description Default
dto dict[str, Any]

Execution payload (same shape as client.executions.get).

 required
client DeepOriginClient | None

Optional API client. Uses the default if not provided.

 None

Returns:

Name Type Description
A Self

class:Metabolism with id, lifecycle fields, and ligands set.

Raises:

Type Description
ValueError

If stored inputs have no ligands.
get_molecules 
get_molecules(
    dto: dict[str, Any] | None = None,
) -> DataFrame

Return molecule-level confidence_tier rows as a DataFrame.

One row per scored SMILES.

Parameters:

Name Type Description Default
dto dict[str, Any] | None

Optional execution payload from executions.create / executions.get.

 None

Returns:

Type Description
DataFrame

DataFrame with ligand_id, smiles, and confidence_tier.

Raises:

Type Description
ValueError

If :attr:id is unset and dto is omitted.
DeepOriginException

If no molecule rows could be parsed.
get_results 
get_results(dto: dict[str, Any] | None = None) -> DataFrame

Return this execution's Metabolism site rows as a DataFrame.

Includes every enzyme the tool scored.

Parameters:

Name Type Description Default
dto dict[str, Any] | None

Optional execution payload from executions.create / executions.get.

 None

Returns:

Type Description
DataFrame

DataFrame with ligand_id, smiles, atom_index,
DataFrame

enzyme, and confidence.

Raises:

Type Description
ValueError

If :attr:id is unset and dto is omitted.
DeepOriginException

If no site rows could be parsed.
run 
run() -> DataFrame

Execute metabolism synchronously and return site rows.

Blocks until the job finishes. Requires fewer than :data:~deeporigin.utils.constants.METABOLISM_WORKFLOW_LIGAND_THRESHOLD ligands; use :meth:start for larger batches. There is no quote=True path. The sites table includes every enzyme the tool scored.

Returns:

Name Type Description
A DataFrame

class:pandas.DataFrame of Metabolism site rows.

Raises:

Type Description
DeepOriginException

If the execution did not complete successfully or no site rows could be parsed.
ValueError

If there are 30 or more ligands.