`deeporigin.drug_discovery.pocket_finder`¶

PocketFinder -- find binding pockets via synchronous or asynchronous execution.

Sync usage (blocking, returns pockets directly)::

pf = PocketFinder(protein)
pf.run(quote=True)   # populates pf.estimate; pf.status == "Quoted"
pockets = pf.run()   # blocking; calls get_results(); populates pf.cost

Async usage (persisted execution, watch in notebook)::

pf = PocketFinder(protein)
pf.start()            # submits async; sets pf.id and pf.status
await pf.watch()      # live Jupyter updates (or pf.sync() in a loop)
pockets = pf.get_results()

Define-by-selection (one pocket from residue/ligand/cofactor selectors)::

pf = PocketFinder(
    protein,
    mode="define-by-selection",
    selections=[{"kind": "ligand", "author": {"chain_id": "A", "resname": "LIG"}}],
    pocket_radius=10.0,
    align_to_pocket=True,
)
pockets = pf.run()

Attributes¶

PocketFinderMode `module-attribute` ¶

PocketFinderMode = Literal[
    "auto-find", "define-by-selection"
]

PocketSelectionKind `module-attribute` ¶

PocketSelectionKind = Literal[
    "residue", "ligand", "cofactor"
]

Classes¶

PocketFinder ¶

Bases: Execution, SyncExecutableMixin, AsyncExecutableMixin, NotebookWatchMixin

Find binding pockets in a protein structure.

Supports mode="auto-find" (classifier; default) and mode="define-by-selection" (one pocket from structured selections).

The execution request body includes sync (true = blocking, false = immediate DTO). :meth:run sets "sync": true and blocks until the run finishes. :meth:start sets "sync": false in inputs (non-blocking); start returns immediately with an execution DTO that you can poll with :meth:sync, wait on with :meth:wait, or watch in Jupyter with :meth:watch. Track async jobs with :meth:sync, :meth:from_id, and :meth:list.

Attributes:

Name	Type	Description
`protein`	`Protein`	The protein to analyse.
`mode`	`PocketFinderMode`	`auto-find` or `define-by-selection`.
`pocket_count`	`int`	Maximum pockets (auto-find).
`pocket_min_size`	`int`	Minimum pocket volume in cubic Angstroms (auto-find).
`selections`	`list[PocketSelection] \| None`	Selectors for define-by-selection (tool wire dicts).
`pocket_radius`	`float`	Half-edge of the docking cube in angstroms (selection).
`align_to_pocket`	`bool`	PCA-orient `box.rotation_deg` from selection atoms.

Attributes¶

align_to_pocket `property` ¶

align_to_pocket: bool

Whether to PCA-orient the box from selection atoms.

mode `property` ¶

mode: PocketFinderMode

Pocket finder mode: auto-find or define-by-selection.

pocket_count `property` ¶

pocket_count: int

Maximum number of pockets to detect (auto-find).

pocket_min_size `property` ¶

pocket_min_size: int

Minimum pocket volume in cubic Angstroms (auto-find).

pocket_radius `property` ¶

pocket_radius: float

Half-edge of the docking cube in angstroms (define-by-selection).

protein `property` ¶

protein: Protein

The protein to analyse.

selections `property` ¶

selections: list[PocketSelection] | None

Selectors for define-by-selection mode, or None for auto-find.

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

tool_key: str = TOOL_KEYS_AND_VERSIONS["pocket_finder"][
    "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 a PocketFinder from a tools execution DTO.

Rehydrates protein and mode-specific inputs from userInputs (falling back to inputs for older payloads). When protein.id is present, the protein is loaded with Protein.from_id(..., download=False) and remote_path_override from the stored input. When only file_path is present (e.g. an unregistered Prepared Protein), builds an in-memory Protein with that remote path.

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`	A `PocketFinder` with `id`, pricing fields, and domain inputs set.

Raises:

Type	Description
`ValueError`	If neither `protein.id` nor `protein.file_path` is present in stored inputs, or selection inputs are invalid.

get_results ¶

get_results(
    dto: dict[str, Any] | None = None,
) -> list[Pocket]

Load pockets for this execution from the data platform or jobOutputs.

Tries :meth:~deeporigin.drug_discovery.structures.pocket.Pocket.from_result first. On failure, parses jobOutputs.pockets from dto, or from client.executions.get when dto is omitted (for example after :meth:~deeporigin.drug_discovery.execution.Execution.from_id).

Parameters:

Name	Type	Description	Default
`dto`	`dict[str, Any] \| None`	Optional execution payload (`executions.create` / `executions.get`). Passing it avoids an extra GET when the data platform path fails but the sync response included `jobOutputs`.	`None`

Returns:

Type	Description
`list[Pocket]`	List of `Pocket` objects for this execution. Each pocket has
`list[Pocket]`	attr:`Pocket.protein` set to this finder's protein.

Raises:

Type	Description
`ValueError`	If :attr:`id` is unset.
`DeepOriginException`	If no pockets could be loaded from the data platform or `jobOutputs`.

run ¶

run(
    *,
    quote: bool = False,
    approve_amount: int | None = None
) -> list[Pocket] | None

Execute pocket finding synchronously (blocking).

Submits one synchronous tools execution (sync=True) and returns the detected pockets via :meth:get_results. The server blocks until the run completes; use :meth:start for async, persisted execution.

Pass quote=True (or approve_amount=0) to request a cost estimate only. In that case the platform returns a Quoted DTO, the instance is updated with estimate and status="Quoted", and None is returned.

Parameters:

Name	Type	Description	Default
`quote`	`bool`	Shorthand for `approve_amount=0`.	`False`
`approve_amount`	`int \| None`	Spend cap forwarded to the platform as `approveAmount`.	`None`

Returns:

Type	Description
`list[Pocket] \| None`	List of `Pocket` objects, or `None` when the platform responds
`list[Pocket] \| None`	with `Quoted` status.

Raises:

Type	Description
`DeepOriginException`	If no pockets could be loaded from the data platform or `jobOutputs`.

PocketSelection ¶

Bases: TypedDict

One residue, ligand, or cofactor selector for define-by-selection mode.

Attributes¶

author `instance-attribute` ¶

author: PocketSelectionAuthor

kind `instance-attribute` ¶

kind: PocketSelectionKind

PocketSelectionAuthor ¶

Bases: TypedDict

PDB/mmCIF author identity for a selected component (tool wire shape).

Attributes¶

chain_id `instance-attribute` ¶

chain_id: str

icode `instance-attribute` ¶

icode: NotRequired[str]

resname `instance-attribute` ¶

resname: NotRequired[str]

resseq `instance-attribute` ¶

resseq: NotRequired[int]

deeporigin.drug_discovery.pocket_finder¶

Attributes¶

PocketFinderMode module-attribute ¶

PocketSelectionKind module-attribute ¶

Classes¶

PocketFinder ¶

Attributes¶

align_to_pocket property ¶

mode property ¶

pocket_count property ¶

pocket_min_size property ¶

pocket_radius property ¶

protein property ¶

selections property ¶

tool_key class-attribute instance-attribute ¶

tool_version instance-attribute ¶

Methods:¶

from_dto classmethod ¶

get_results ¶

run ¶

PocketSelection ¶

Attributes¶

author instance-attribute ¶

kind instance-attribute ¶

PocketSelectionAuthor ¶

Attributes¶

chain_id instance-attribute ¶

icode instance-attribute ¶

resname instance-attribute ¶

resseq instance-attribute ¶

`deeporigin.drug_discovery.pocket_finder`¶

PocketFinderMode `module-attribute` ¶

PocketSelectionKind `module-attribute` ¶

align_to_pocket `property` ¶

mode `property` ¶

pocket_count `property` ¶

pocket_min_size `property` ¶

pocket_radius `property` ¶

protein `property` ¶

selections `property` ¶

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

tool_version `instance-attribute` ¶

from_dto `classmethod` ¶

author `instance-attribute` ¶

kind `instance-attribute` ¶

chain_id `instance-attribute` ¶

icode `instance-attribute` ¶

resname `instance-attribute` ¶

resseq `instance-attribute` ¶