`deeporigin.drug_discovery.Pocket`¶

Bases: Entity

Class representing a binding pocket in a protein structure.

This class provides essential methods for pocket analysis, visualization, and coordinate manipulation.

Attributes¶

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

apolar_sasa: Optional[float] = 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'

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

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

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

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

total_sasa: Optional[float] = None

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

volume: Optional[float] = None

Functions¶

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.

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

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 ¶

local_path class-attribute instance-attribute ¶

name 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_id class-attribute instance-attribute ¶

remote_path class-attribute instance-attribute ¶

total_sasa class-attribute instance-attribute ¶

volume class-attribute instance-attribute ¶

Functions¶

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 ¶

sync ¶

to_file ¶

to_hash ¶

to_pdb_file ¶

update_coordinates ¶

upload ¶

`deeporigin.drug_discovery.Pocket`¶

apolar_sasa `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` ¶

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

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

name `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_id `class-attribute` `instance-attribute` ¶

remote_path `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` ¶