`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(). 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 for this execution.

Class-level :meth:fetch_results / :meth:fetch_molecules load indexed rows for a ligand set from the data platform (any past jobs) by ligand_id. Before run / start, if every ligand has a platform id and every id already has a Metabolism molecule, the client refuses (no execution). If the job still proceeds and any id is already indexed, it warns. There is no force/recompute path.

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.

Batches larger than the platform Inline ligand cap (:data:~deeporigin.utils.constants.METABOLISM_INLINE_LIGAND_CAP) dump a Ligand list file to UFA and submit inputs.ligands_file on :meth:start (transparent to the caller).

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()
mols = job.get_molecules()

Fetch indexed rows without starting a job::

sites = Metabolism.fetch_results(ligands=ligands)
mols = Metabolism.fetch_molecules(ligands=ligands)

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 / :meth:get_molecules (data platform first, jobOutputs fallback). Batches above :data:~deeporigin.utils.constants.METABOLISM_INLINE_LIGAND_CAP upload a Ligand list file and pass ligands_file instead of inline ligands.

Use :meth:fetch_results / :meth:fetch_molecules to read indexed rows for a ligand set without starting a job.

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:¶

fetch_molecules `classmethod` ¶

fetch_molecules(
    ligands: Ligand | list[Ligand] | LigandSet,
    *,
    client: DeepOriginClient | None = None
) -> DataFrame

Load indexed Metabolism molecule rows for ligands (any past jobs).

Queries the data platform by platform ligand_id. Does not start an execution. Partial or empty tables are OK when some ligands lack an id or have no indexed MetabolismMolecule. Missing smiles on indexed rows is filled from ligands by ligand_id.

Parameters:

Name	Type	Description	Default
`ligands`	`Ligand \| list[Ligand] \| LigandSet`	A ligand, list, or :class:`LigandSet`.	required
`client`	`DeepOriginClient \| None`	Optional API client. Uses the default if not provided.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with preferred columns `ligand_id`, `smiles`, and
`DataFrame`	`confidence_tier`.

fetch_results `classmethod` ¶

fetch_results(
    ligands: Ligand | list[Ligand] | LigandSet,
    *,
    client: DeepOriginClient | None = None
) -> DataFrame

Load indexed Metabolism site rows for ligands (any past jobs).

Queries the data platform by platform ligand_id. Does not start an execution. Ligands without an id contribute no filter keys; missing indexed rows are omitted (partial or empty tables are OK). Missing smiles on indexed rows is filled from ligands by ligand_id.

Parameters:

Name	Type	Description	Default
`ligands`	`Ligand \| list[Ligand] \| LigandSet`	A ligand, list, or :class:`LigandSet`.	required
`client`	`DeepOriginClient \| None`	Optional API client. Uses the default if not provided.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with preferred columns `ligand_id`, `smiles`,
`DataFrame`	`atom_index`, `enzyme`, and `confidence`.

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). When only ligands_file is present, downloads and parses that UFA Ligand list file.

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, or `ligands_file` cannot be downloaded or parsed.

get_molecules ¶

get_molecules(
    dto: dict[str, Any] | None = None,
) -> DataFrame

Return molecule-level confidence_tier rows as a DataFrame.

Prefers data-platform result-explorer rows for this execution (result_type=metabolismmolecule), then falls back to jobOutputs.molecules. One row per scored SMILES.

For indexed molecules across any past jobs (no execution required), use :meth:fetch_molecules instead of calling this on the class with ligands.

Parameters:

Name	Type	Description	Default
`dto`	`dict[str, Any] \| None`	Optional execution payload from `executions.create` / `executions.get` used only for the jobOutputs fallback.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with `ligand_id`, `smiles`, and `confidence_tier`.

Raises:

Type	Description
`TypeError`	If called as `Metabolism.get_molecules(ligands)`.
`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.

Prefers data-platform result-explorer rows for this execution (result_type=metabolismsite), then falls back to jobOutputs.sites. Includes every enzyme the tool scored.

For indexed sites across any past jobs (no execution required), use :meth:fetch_results instead of calling this on the class with ligands.

Parameters:

Name	Type	Description	Default
`dto`	`dict[str, Any] \| None`	Optional execution payload from `executions.create` / `executions.get` used only for the jobOutputs fallback.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with `ligand_id`, `smiles`, `atom_index`,
`DataFrame`	`enzyme`, and `confidence`.

Raises:

Type	Description
`TypeError`	If called as `Metabolism.get_results(ligands)`.
`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.

Refuses before create when every ligand has a platform id and every id already has a Metabolism molecule (use :meth:fetch_results instead).

Returns:

Name	Type	Description
`A`	`DataFrame`	class:`pandas.DataFrame` of Metabolism site rows.

Raises:

Type	Description
`DeepOriginException`	If all ligands are already scored, the execution did not complete successfully, or no site rows could be parsed.
`ValueError`	If there are 30 or more ligands.

deeporigin.drug_discovery.metabolism¶

Classes¶

Metabolism ¶

Attributes¶

ligands property ¶

name instance-attribute ¶

tool_key class-attribute instance-attribute ¶

tool_version class-attribute instance-attribute ¶

Methods:¶

fetch_molecules classmethod ¶

fetch_results classmethod ¶

from_dto classmethod ¶

get_molecules ¶

get_results ¶

run ¶

`deeporigin.drug_discovery.metabolism`¶

ligands `property` ¶

name `instance-attribute` ¶

tool_key `class-attribute` `instance-attribute` ¶

tool_version `class-attribute` `instance-attribute` ¶

fetch_molecules `classmethod` ¶

fetch_results `classmethod` ¶

from_dto `classmethod` ¶