Skip to content

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()

Classes

PocketFinder

Bases: Execution, SyncExecutableMixin, AsyncExecutableMixin, NotebookWatchMixin

Find binding pockets in a protein structure.

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.
pocket_count int

Maximum number of pockets to detect.
pocket_min_size int

Minimum pocket volume in cubic Angstroms.

Attributes

pocket_count property 
pocket_count: int

Maximum number of pockets to detect.

pocket_min_size property 
pocket_min_size: int

Minimum pocket volume in cubic Angstroms.

protein property 
protein: Protein

The protein to analyse.

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, pocket_count, and pocket_min_size from userInputs (falling back to inputs for older payloads). The protein is loaded with Protein.from_id(..., download=False) and remote_path_override from the stored input, matching :meth:_make_payload / :meth:Docking.from_dto.

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 protein.id is missing from stored inputs.
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.

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.