Skip to content

deeporigin.drug_discovery.enumerator

Enumerator -- generate analogue libraries from a parent ligand (served, sync-only).

Backed by the served platform tool deeporigin.enumerator (a direct execution). One :class:Enumerator is configured with a single job_type and executed with a blocking :meth:run, which returns a :class:pandas.DataFrame.

The tool exposes four job_type values:

  • SCAFFOLD -- CReM matched-molecular-pair (MMP) enumeration that grows a fragment at a single attachment atom (one replace_ix index).
  • ANALOGUE -- CReM MMP enumeration that swaps a connected fragment (one or more replace_ix indices forming a connected substructure).
  • AVAILABLE_REACTIONS -- discovers named-reaction sites on the parent and returns their atom indices. Writes no CSV; the DataFrame is built from the inline result list.
  • REACTION -- enumerates products against the Enamine fragment library at explicit reaction_sites. Each site must match a hit returned by a prior AVAILABLE_REACTIONS run.

SCAFFOLD and ANALOGUE are the two MMP flavors.

Usage::

from deeporigin.drug_discovery import Enumerator, Ligand

parent = Ligand.from_smiles("Brc1ccccc1")

# MMP: grow a fragment at atom 0
df = Enumerator(ligand=parent, job_type="SCAFFOLD", replace_ix=0).run()

# Discover reaction sites, then enumerate against them
sites = Enumerator(ligand=parent, job_type="AVAILABLE_REACTIONS").run()
df = Enumerator(
    ligand=parent,
    job_type="REACTION",
    reaction_sites=[
        {"reaction_id": "suzuki", "reactant_role": "core_halide", "atom_indices": [0, 1]},
    ],
).run()

Classes

Enumerator

Bases: Execution, SyncExecutableMixin

Enumerate analogues of a parent ligand via the served enumerator tool.

Configure the instance with a parent :class:~deeporigin.drug_discovery.structures.ligand.Ligand, a job_type, and its mode-specific parameters, then call :meth:run to execute synchronously and receive a :class:pandas.DataFrame.

For SCAFFOLD / ANALOGUE / REACTION the DataFrame is parsed from the tool's descriptor-enriched results.csv. For AVAILABLE_REACTIONS the DataFrame is built from the inline available_reactions list (no CSV is written).

Attributes:

Name Type Description
ligand Ligand

Parent ligand whose smiles (and optional id) is enumerated.
job_type str

One of SCAFFOLD, ANALOGUE, AVAILABLE_REACTIONS, REACTION.
replace_ix list[int] | None

RDKit atom indices marking the MMP enumeration site (MMP modes).
reaction_sites list[dict[str, Any]] | None

Named-reaction sites for REACTION enumeration.
radius int

CReM environment radius (MMP modes).
max_fragment_size int

Maximum heavy atoms in the added/replacement fragment (MMP modes).
cap_hit bool | None

Whether the last run hit the platform enumeration cap (MMP/REACTION), or None before a run or for AVAILABLE_REACTIONS.

Attributes

cap_hit property 
cap_hit: bool | None

Whether the last MMP/REACTION run hit the platform enumeration cap.

None before :meth:run, or for AVAILABLE_REACTIONS (which has no cap).

job_type property 
job_type: str

Enumeration mode for this run (read-only).

ligand property 
ligand: Ligand

Parent ligand targeted by this enumeration (read-only).

max_fragment_size property 
max_fragment_size: int

Maximum heavy atoms in the added/replacement fragment (MMP modes, read-only).

radius property 
radius: int

CReM environment radius used for MMP modes (read-only).

reaction_sites property 
reaction_sites: list[dict[str, Any]] | None

Named-reaction sites for REACTION enumeration, if any (read-only).

replace_ix property 
replace_ix: list[int] | None

RDKit atom indices marking the MMP enumeration site, if any (read-only).

tool_key class-attribute instance-attribute 
tool_key: str = TOOL_KEYS_AND_VERSIONS["enumerator"][
    "tool_key"
]
tool_version instance-attribute 
tool_version = tool_version

Methods:

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

Construct an Enumerator from a tools execution DTO.

Rehydrates the parent ligand and mode-specific inputs from userInputs (falling back to inputs for older payloads).

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:

Type Description
Self

An Enumerator with id, pricing fields, and domain inputs set.

Raises:

Type Description
ValueError

If the stored inputs are missing a ligand SMILES or carry a missing/unknown job_type.
get_results 
get_results(dto: dict[str, Any] | None = None) -> DataFrame

Return this execution's results as a :class:pandas.DataFrame.

Reads jobOutputs from dto (or fetches it via client.executions.get when omitted, e.g. after :meth:~deeporigin.drug_discovery.execution.Execution.from_id).

Parameters:

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

Optional execution payload from executions.create / executions.get. Passing it avoids an extra GET.

 None

Returns:

Type Description
DataFrame

A DataFrame of enumeration products (MMP / REACTION) or discovered
DataFrame

reaction sites (AVAILABLE_REACTIONS).

Raises:

Type Description
ValueError

If :attr:id is unset.
DeepOriginException

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

Execute the enumeration synchronously (blocking) and return a DataFrame.

Submits one synchronous execution (sync=True), applies the response via :meth:~deeporigin.drug_discovery.execution.Execution.update_from_dto, and returns results via :meth:get_results.

Returns:

Name Type Description
A DataFrame

class:pandas.DataFrame. For SCAFFOLD / ANALOGUE /
DataFrame

REACTION it is the descriptor-enriched results.csv; for
DataFrame

AVAILABLE_REACTIONS it has columns
DataFrame

data:~deeporigin.utils.constants.ENUMERATOR_AVAILABLE_REACTIONS_COLUMNS.

Raises:

Type Description
DeepOriginException

If the execution did not complete successfully or no results could be parsed.