`deeporigin.drug_discovery.Pocket`¶

Bases: Entity

Binding pocket in a protein structure.

PocketFinder results attach a parent :class:Protein on :attr:protein (and :attr:protein_id when known). :meth:show overlays this pocket on that protein.

Attributes¶

apolar_sasa `class-attribute` `instance-attribute` ¶

apolar_sasa: Optional[float] = None

box `class-attribute` `instance-attribute` ¶

box: Optional[PocketBox] = None

box_size_x `class-attribute` `instance-attribute` ¶

box_size_x: Optional[float] = None

box_size_y `class-attribute` `instance-attribute` ¶

box_size_y: Optional[float] = None

box_size_z `class-attribute` `instance-attribute` ¶

box_size_z: Optional[float] = None

center `class-attribute` `instance-attribute` ¶

center: Optional[list[float]] = None

color `class-attribute` `instance-attribute` ¶

color: str = 'red'

component_id `class-attribute` `instance-attribute` ¶

component_id: Optional[str] = None

coordinates `class-attribute` `instance-attribute` ¶

coordinates: Optional[ndarray] = None

drugability_score `class-attribute` `instance-attribute` ¶

drugability_score: Optional[float] = None

hydrophobicity `class-attribute` `instance-attribute` ¶

hydrophobicity: Optional[float] = None

id `class-attribute` `instance-attribute` ¶

id: str | None = field(default=None, kw_only=True)

index `class-attribute` `instance-attribute` ¶

index: Optional[int] = 0

ligand_id `class-attribute` `instance-attribute` ¶

ligand_id: Optional[str] = None

ligand_name `class-attribute` `instance-attribute` ¶

ligand_name: Optional[str] = None

local_path `class-attribute` `instance-attribute` ¶

local_path: str | None = field(default=None, kw_only=True)

name `class-attribute` `instance-attribute` ¶

name: Optional[str] = None

origin `class-attribute` `instance-attribute` ¶

origin: PocketOrigin | str | None = None

pdb_id `class-attribute` `instance-attribute` ¶

pdb_id: Optional[str] = None

pocket_count `class-attribute` `instance-attribute` ¶

pocket_count: Optional[int] = None

pocket_min_size `class-attribute` `instance-attribute` ¶

pocket_min_size: Optional[int] = None

polar_apolar_sasa_ratio `class-attribute` `instance-attribute` ¶

polar_apolar_sasa_ratio: Optional[float] = None

polar_sasa `class-attribute` `instance-attribute` ¶

polar_sasa: Optional[float] = None

polarity `class-attribute` `instance-attribute` ¶

polarity: Optional[float] = None

project_id `class-attribute` `instance-attribute` ¶

project_id: str | None = field(default=None, kw_only=True)

props `class-attribute` `instance-attribute` ¶

props: Optional[dict[str, Any]] = field(
    default_factory=dict
)

protein `class-attribute` `instance-attribute` ¶

protein: Protein | None = field(
    default=None, repr=False, compare=False
)

protein_id `class-attribute` `instance-attribute` ¶

protein_id: Optional[str] = None

remote_path `class-attribute` `instance-attribute` ¶

remote_path: str | None = field(default=None, kw_only=True)

selection_names `class-attribute` `instance-attribute` ¶

selection_names: Optional[list[str]] = None

tags `class-attribute` `instance-attribute` ¶

tags: dict[str, Any] | None = field(
    default=None, kw_only=True
)

total_sasa `class-attribute` `instance-attribute` ¶

total_sasa: Optional[float] = None

volume `class-attribute` `instance-attribute` ¶

volume: Optional[float] = None

Methods:¶

download ¶

download(
    *,
    lazy: bool = True,
    client: DeepOriginClient | None = None
) -> str

Download the entity file from remote storage.

No-ops if local_path is already set.

Parameters:

Name	Type	Description	Default
`client`	`DeepOriginClient \| None`	DeepOriginClient instance. If None, uses DeepOriginClient().	`None`

Returns:

Type	Description
`str`	The local file path.

Raises:

Type	Description
`ValueError`	If neither local_path nor remote_path is available.

ensure_remote_path ¶

ensure_remote_path(
    *, client: DeepOriginClient, label: str
) -> None

Ensure :attr:remote_path is set after a lazy :meth:sync may have no-oped.

If the entity already has a platform id but remote_path was never populated (e.g. rehydrated metadata only), sync(lazy=True) returns early. This performs a full sync when needed, then raises if the path is still missing.

Parameters:

Name	Type	Description	Default
`client`	`DeepOriginClient`	Authenticated client for sync/upload.	required
`label`	`str`	Human-readable name for error messages (e.g. `"Protein"`).	required

Raises:

Type	Description
`ValueError`	If `remote_path` cannot be determined after sync.

from_id `classmethod` ¶

from_id(
    id: str, *, client: Optional["DeepOriginClient"] = None
) -> Self

Create a Pocket from a result-explorer record ID.

Fetches the single record and stores the remote path without downloading. The PDB file is fetched lazily when coordinates are first accessed.

Parameters:

Name	Type	Description	Default
`id`	`str`	Result-explorer record ID of the pocket.	required
`client`	`Optional['DeepOriginClient']`	Optional DeepOriginClient instance. If not provided, uses the default client.	`None`

Returns:

Type	Description
`Self`	A Pocket with properties populated from the record.

Raises:

Type	Description
`ValueError`	If no record is found for the given ID.

from_json `classmethod` ¶

from_json(
    data: list[dict[str, Any]],
    *,
    client: Optional["DeepOriginClient"] = None
) -> list[Self]

Create a list of Pocket objects from a JSON pocket list.

Each entry should contain at least one of file_path / local_path or remote_path. A file_path that does not resolve to an existing local file is treated as a platform remote path (for example tool-runs/.../pocket_1.pdb); coordinates load lazily on first access via :meth:_ensure_coordinates / :meth:download. When file_path points to a real file on disk it is used as local_path and coordinates load in :meth:__post_init__.

Known property keys (volume, total_SASA, etc.) are mapped to dedicated attributes. The protein_id key is mapped to its own attribute. Any remaining unknown keys go into props.

Parameters:

Name	Type	Description	Default
`data`	`list[dict[str, Any]]`	List of pocket dicts, e.g. the value of the `"pockets"` key returned by the pocket-finder tool.	required
`client`	`Optional['DeepOriginClient']`	Optional client to use for lazy downloads. When provided, stored on each Pocket and used by :meth:`download` when coordinates are first accessed. When an entry omits `project_id`, each Pocket uses `getattr(client, "project_id", None)` when a client is given.	`None`

Returns:

Type	Description
`list[Self]`	List of Pocket objects with properties populated from the dicts.

from_ligand `classmethod` ¶

from_ligand(
    ligand: "Ligand", name: Optional[str] = None
) -> Self

Create a Pocket instance from a Ligand instance.

from_pdb_file `classmethod` ¶

from_pdb_file(
    pdb_file_path: str | Path,
    name: Optional[str] = None,
    **kwargs: Any
) -> Self

Create a Pocket instance from a PDB file.

Parameters:

Name	Type	Description	Default
`pdb_file_path`	`str \| Path`	Path to the PDB file.	required
`name`	`Optional[str]`	Name for the pocket.	`None`
`**kwargs`	`Any`	Additional arguments to pass to the Pocket constructor.	`{}`

Returns:

Name	Type	Description
`Pocket`	`Self`	A new Pocket instance.

from_remote_file `classmethod` ¶

from_remote_file(
    remote_path: str,
    *,
    client: DeepOriginClient | None = None,
    lazy: bool = True,
    name: Optional[str] = None,
    **kwargs: Any
) -> Self

Create a Pocket from a PDB file stored on the platform.

Downloads the file via :meth:deeporigin.platform.files.FilesClient.download, then loads it with :meth:from_pdb_file.

Parameters:

Name	Type	Description	Default
`remote_path`	`str`	Platform file path (e.g. org storage path) to the PDB file.	required
`client`	`DeepOriginClient \| None`	DeepOrigin client used for download. If `None`, uses `DeepOriginClient()`.	`None`
`lazy`	`bool`	Passed to `files.download`; if `True`, skip download when the file already exists locally at the default cache location.	`True`
`name`	`Optional[str]`	Optional pocket name; defaults to the downloaded file stem (see :meth:`from_pdb_file`).	`None`
`**kwargs`	`Any`	Additional arguments passed to :meth:`from_pdb_file`.	`{}`

Returns:

Name	Type	Description
`Pocket`	`Self`	A pocket with :attr:`~deeporigin.drug_discovery.structures.entity.Entity.remote_path`
	`Self`	set to `remote_path` and :attr:`~deeporigin.drug_discovery.structures.entity.Entity.local_path`
	`Self`	set to the downloaded file path.

from_residue_number `classmethod` ¶

from_residue_number(
    protein,
    residue_number: int,
    chain_id: str | None = None,
    cutoff: float = 5.0,
) -> Self

Creates a pocket centered on a given residue (by number)

Parameters:

Name	Type	Description	Default
`protein`	`Protein`	A DeepOrigin Protein Object	required
`residue_number`	`int`	Residue number of the target residue	required
`chain_id`	`str`	Chain ID that the residue is in	`None`
`cutoff`	`float`	Minimum distance cutoff (Angstroms) from target residue to be included in pocket	`5.0`

Returns:

Type	Description
`Self`	A Pocket object matching the above design.

from_result `classmethod` ¶

from_result(
    *,
    protein_id: str | None = None,
    execution_id: str | None = None,
    pocket_count: int | None = None,
    pocket_min_size: int | None = None,
    client: Optional["DeepOriginClient"] = None
) -> list[Self]

Create Pocket objects from pocketfinder results in the data platform.

Fetches pocketfinder results for the given protein and stores the remote paths without downloading. PDB files are fetched lazily when coordinates are first accessed.

Parameters:

Name	Type	Description	Default
`protein_id`	`str \| None`	Protein ID to fetch pocket results for.	`None`
`execution_id`	`str \| None`	Optional compute job ID to filter by.	`None`
`pocket_count`	`int \| None`	Optional maximum number of pockets to filter by.	`None`
`pocket_min_size`	`int \| None`	Optional minimum pocket volume in cubic Angstroms to filter by.	`None`
`client`	`Optional['DeepOriginClient']`	Optional DeepOriginClient instance. If not provided, uses the default client.	`None`

Returns:

Type	Description
`list[Self]`	List of Pocket objects with properties populated from the results.

Raises:

Type	Description
`ValueError`	If no pocket results are found for the protein.

get_center ¶

get_center() -> ndarray

Get the center of the pocket.

Returns the pre-computed center when available, otherwise falls back to computing the mean of the loaded coordinates.

Returns:

Type	Description
`ndarray`	np.ndarray: A numpy array of shape (3,) with the pocket center.

resolved_project_id ¶

resolved_project_id(
    client: DeepOriginClient | None = None,
) -> str | None

Data platform project id for API calls.

Returns :attr:project_id when set; otherwise client.project_id when client is given; otherwise None. Does not read the filesystem.

Parameters:

Name	Type	Description	Default
`client`	`DeepOriginClient \| None`	Optional platform client (e.g. the one passed to :meth:`sync`).	`None`

Returns:

Type	Description
`str \| None`	Project id string, or None if neither the entity nor the client
`str \| None`	provides one.

show ¶

show() -> Any

Visualize this pocket overlaid on its parent protein.

Sugar for protein.show(pockets=[self]). Uses :attr:protein when attached; otherwise loads the parent with :meth:~deeporigin.drug_discovery.structures.protein.Protein.from_id from :attr:protein_id. The parent structure is downloaded with this pocket's client when only metadata is attached, and this pocket is written to (or downloaded to) a local file when it has none.

Returns:

Type	Description
`Any`	Result of :meth:`~deeporigin.drug_discovery.structures.protein.Protein.show`.

Raises:

Type	Description
`DeepOriginException`	If no parent protein can be resolved, or if loading the protein by id fails.

show_box ¶

show_box() -> Any

Visualize the docking search box for this pocket on its parent protein.

Static preview of the same wireframe geometry docking submits (center, box sizes, and inferred orientation from :attr:box when present). Does not support interactive editing or pose overlays — use :meth:~deeporigin.drug_discovery.docking.Docking.show_box for those.

Parent resolution matches :meth:show: attached :attr:protein, else :meth:~deeporigin.drug_discovery.structures.protein.Protein.from_id via :attr:protein_id. Unlike :meth:show, this does not require a local pocket structure file (the box uses center and extents only).

Returns:

Type	Description
`Any`	Result of the notebook HTML renderer for the protein + box.

Raises:

Type	Description
`DeepOriginException`	If no parent protein can be resolved, or if loading the protein fails.

sync ¶

sync(
    *,
    lazy: bool = False,
    client: Optional[DeepOriginClient] = None,
    remote_path: Optional[str] = None
) -> None

Upload pocket coordinates to remote storage.

Unlike :class:Protein and :class:Ligand, pockets are not looked up in the entities API; this only uploads the generated PDB so :attr:remote_path is set for tools that need a file reference.

Parameters:

Name	Type	Description	Default
`lazy`	`bool`	If True, skip when the pocket already has a platform `id`.	`False`
`client`	`Optional[DeepOriginClient]`	DeepOrigin client. If None, uses `DeepOriginClient()`.	`None`
`remote_path`	`Optional[str]`	Optional explicit destination path on the file server.	`None`

to_file ¶

to_file(file_path: str | Path | None = None) -> str

Write pocket coordinates to a PDB file.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| Path \| None`	Destination path. When `None` a temporary file is created; the caller is responsible for deleting it when done.	`None`

Returns:

Type	Description
`str`	The path the file was written to.

to_hash ¶

to_hash() -> str

Compute a hash of the pocket PDB content.

Returns:

Type	Description
`str`	SHA-256 hex digest of the generated PDB string.

to_pdb_file ¶

to_pdb_file(output_path: str)

Write coordinates to a PDB file.

Parameters:

Name	Type	Description	Default
`output_path`	`str`	Destination file path.	required

update_coordinates ¶

update_coordinates(coords: ndarray)

update coordinates of the pocket

upload ¶

upload(
    *,
    client: DeepOriginClient | None = None,
    remote_path: str | None = None
) -> None

Upload the entity to the remote server.

Serializes via :meth:to_file with :attr:remote_path temporarily cleared so subclasses that guard exports when only remote metadata is present (e.g. :meth:Ligand.to_sdf) still write from in-memory state on repeat uploads.

Parameters:

Name	Type	Description	Default
`client`	`DeepOriginClient \| None`	DeepOriginClient instance. If None, uses DeepOriginClient().	`None`
`remote_path`	`str \| None`	Custom remote path to upload to. When provided, sets :attr:`remote_path` before uploading. If :attr:`remote_path` is still unset, it is set to the default hash-based path.	`None`

deeporigin.drug_discovery.Pocket¶

Attributes¶

apolar_sasa class-attribute instance-attribute ¶

box class-attribute instance-attribute ¶

box_size_x class-attribute instance-attribute ¶

box_size_y class-attribute instance-attribute ¶

box_size_z class-attribute instance-attribute ¶

center class-attribute instance-attribute ¶

color class-attribute instance-attribute ¶

component_id class-attribute instance-attribute ¶

coordinates class-attribute instance-attribute ¶

drugability_score class-attribute instance-attribute ¶

hydrophobicity class-attribute instance-attribute ¶

id class-attribute instance-attribute ¶

index class-attribute instance-attribute ¶

ligand_id class-attribute instance-attribute ¶

ligand_name class-attribute instance-attribute ¶

local_path class-attribute instance-attribute ¶

name class-attribute instance-attribute ¶

origin class-attribute instance-attribute ¶

pdb_id class-attribute instance-attribute ¶

pocket_count class-attribute instance-attribute ¶

pocket_min_size class-attribute instance-attribute ¶

polar_apolar_sasa_ratio class-attribute instance-attribute ¶

polar_sasa class-attribute instance-attribute ¶

polarity class-attribute instance-attribute ¶

project_id class-attribute instance-attribute ¶

props class-attribute instance-attribute ¶

protein class-attribute instance-attribute ¶

protein_id class-attribute instance-attribute ¶

remote_path class-attribute instance-attribute ¶

selection_names class-attribute instance-attribute ¶

tags class-attribute instance-attribute ¶

total_sasa class-attribute instance-attribute ¶

volume class-attribute instance-attribute ¶

Methods:¶

download ¶

ensure_remote_path ¶

from_id classmethod ¶

from_json classmethod ¶

from_ligand classmethod ¶

from_pdb_file classmethod ¶

from_remote_file classmethod ¶

from_residue_number classmethod ¶

from_result classmethod ¶

get_center ¶

resolved_project_id ¶

show ¶

show_box ¶

sync ¶

to_file ¶

to_hash ¶

to_pdb_file ¶

update_coordinates ¶

upload ¶

`deeporigin.drug_discovery.Pocket`¶

apolar_sasa `class-attribute` `instance-attribute` ¶

box `class-attribute` `instance-attribute` ¶

box_size_x `class-attribute` `instance-attribute` ¶

box_size_y `class-attribute` `instance-attribute` ¶

box_size_z `class-attribute` `instance-attribute` ¶

center `class-attribute` `instance-attribute` ¶

color `class-attribute` `instance-attribute` ¶

component_id `class-attribute` `instance-attribute` ¶

coordinates `class-attribute` `instance-attribute` ¶

drugability_score `class-attribute` `instance-attribute` ¶

hydrophobicity `class-attribute` `instance-attribute` ¶

id `class-attribute` `instance-attribute` ¶

index `class-attribute` `instance-attribute` ¶

ligand_id `class-attribute` `instance-attribute` ¶

ligand_name `class-attribute` `instance-attribute` ¶

local_path `class-attribute` `instance-attribute` ¶

name `class-attribute` `instance-attribute` ¶

origin `class-attribute` `instance-attribute` ¶

pdb_id `class-attribute` `instance-attribute` ¶

pocket_count `class-attribute` `instance-attribute` ¶

pocket_min_size `class-attribute` `instance-attribute` ¶

polar_apolar_sasa_ratio `class-attribute` `instance-attribute` ¶

polar_sasa `class-attribute` `instance-attribute` ¶

polarity `class-attribute` `instance-attribute` ¶

project_id `class-attribute` `instance-attribute` ¶

props `class-attribute` `instance-attribute` ¶

protein `class-attribute` `instance-attribute` ¶

protein_id `class-attribute` `instance-attribute` ¶

remote_path `class-attribute` `instance-attribute` ¶

selection_names `class-attribute` `instance-attribute` ¶

tags `class-attribute` `instance-attribute` ¶

total_sasa `class-attribute` `instance-attribute` ¶

volume `class-attribute` `instance-attribute` ¶

from_id `classmethod` ¶

from_json `classmethod` ¶

from_ligand `classmethod` ¶

from_pdb_file `classmethod` ¶

from_remote_file `classmethod` ¶

from_residue_number `classmethod` ¶

from_result `classmethod` ¶